History

co-op-translator[bot] 5001e53945 🌐 Update translations via Co-op Translator (#548 ) Co-authored-by: leestott <leestott@users.noreply.github.com>		4 weeks ago
..
README.md	🌐 Update translations via Co-op Translator (#548 )	4 weeks ago
assignment.md	🌐 Update translations via Co-op Translator (#548 )	4 weeks ago

README.md

Unescape Escape

גדרות גיאוגרפיות

סקיצה מאת ניטיה נאראסימן. לחצו על התמונה לגרסה גדולה יותר.

הווידאו הבא מספק סקירה על גדרות גיאוגרפיות וכיצד להשתמש בהן ב-Azure Maps, נושאים שיכוסו בשיעור זה:

🎥 לחצו על התמונה למעלה לצפייה בווידאו

חידון לפני השיעור

מבוא

בשלושת השיעורים האחרונים השתמשתם ב-IoT כדי לאתר משאיות שמובילות את התוצרת שלכם מהחווה למרכז עיבוד. אספתם נתוני GPS, שלחתם אותם לענן לאחסון, והצגתם אותם על מפה. השלב הבא לשיפור היעילות של שרשרת האספקה שלכם הוא לקבל התראה כאשר משאית עומדת להגיע למרכז העיבוד, כך שהצוות שצריך לפרוק את המשאית יוכל להיות מוכן עם מלגזות וציוד אחר ברגע שהרכב מגיע. כך ניתן לפרוק במהירות, ולחסוך תשלום על זמן המתנה של משאית ונהג.

בשיעור זה תלמדו על גדרות גיאוגרפיות - אזורים גיאוגרפיים מוגדרים, כמו אזור שנמצא במרחק נסיעה של 2 ק"מ ממרכז עיבוד, וכיצד לבדוק אם קואורדינטות GPS נמצאות בתוך או מחוץ לגדר גיאוגרפית, כך שתוכלו לדעת אם חיישן ה-GPS שלכם הגיע או עזב אזור מסוים.

בשיעור זה נעסוק ב:

🗑 זהו השיעור האחרון בפרויקט זה, אז לאחר השלמת השיעור והמשימה, אל תשכחו לנקות את שירותי הענן שלכם. תצטרכו את השירותים כדי להשלים את המשימה, אז ודאו שאתם מסיימים אותה קודם.

עיינו ב-מדריך לניקוי הפרויקט שלכם במידת הצורך להוראות כיצד לעשות זאת.

מהן גדרות גיאוגרפיות

גדר גיאוגרפית היא גבול וירטואלי לאזור גיאוגרפי בעולם האמיתי. גדרות גיאוגרפיות יכולות להיות מעגלים המוגדרים כנקודה ורדיוס (לדוגמה, מעגל ברוחב 100 מטר סביב בניין), או פוליגון המכסה אזור כמו אזור בית ספר, גבולות עיר, או קמפוס אוניברסיטה או משרדים.

💁 ייתכן שכבר השתמשתם בגדרות גיאוגרפיות מבלי לדעת. אם הגדרתם תזכורת באפליקציית התזכורות של iOS או Google Keep בהתבסס על מיקום, השתמשתם בגדר גיאוגרפית. אפליקציות אלו יגדירו גדר גיאוגרפית בהתבסס על המיקום שניתן ויתריעו לכם כאשר הטלפון שלכם נכנס לגדר הגיאוגרפית.

ישנן סיבות רבות מדוע תרצו לדעת אם רכב נמצא בתוך או מחוץ לגדר גיאוגרפית:

הכנה לפריקה - קבלת התראה על כך שרכב הגיע לאתר מאפשרת לצוות להיות מוכן לפרוק את הרכב, מה שמפחית את זמן ההמתנה של הרכב. כך נהג יכול לבצע יותר משלוחים ביום עם פחות זמן המתנה.
ציות למיסוי - במדינות מסוימות, כמו ניו זילנד, נגבים מיסי כבישים עבור רכבי דיזל בהתבסס על משקל הרכב כאשר הוא נוסע בכבישים ציבוריים בלבד. שימוש בגדרות גיאוגרפיות מאפשר לעקוב אחר הקילומטראז' שנעשה בכבישים ציבוריים לעומת כבישים פרטיים באתרים כמו חוות או אזורי כריתה.
מעקב אחר גניבה - אם רכב אמור להישאר באזור מסוים, כמו חווה, והוא עוזב את הגדר הגיאוגרפית, ייתכן שהוא נגנב.
ציות למיקום - חלקים מסוימים באתר עבודה, חווה או מפעל עשויים להיות מחוץ לתחום עבור רכבים מסוימים, כמו שמירה על רכבים שנושאים דשנים מלאכותיים וחומרי הדברה הרחק משדות שמגדלים בהם תוצרת אורגנית. אם נכנסים לגדר גיאוגרפית, הרכב נמצא מחוץ לציות, וניתן להתריע לנהג.

✅ האם אתם יכולים לחשוב על שימושים נוספים לגדרות גיאוגרפיות?

Azure Maps, השירות שבו השתמשתם בשיעור הקודם כדי להציג נתוני GPS, מאפשר לכם להגדיר גדרות גיאוגרפיות ואז לבדוק אם נקודה נמצאת בתוך או מחוץ לגדר הגיאוגרפית.

הגדרת גדר גיאוגרפית

גדרות גיאוגרפיות מוגדרות באמצעות GeoJSON, בדיוק כמו הנקודות שנוספו למפה בשיעור הקודם. במקרה זה, במקום להיות FeatureCollection של ערכי Point, זהו FeatureCollection שמכיל Polygon.

{
   "type": "FeatureCollection",
   "features": [
     {
       "type": "Feature",
       "geometry": {
         "type": "Polygon",
         "coordinates": [
           [
             [
               -122.13393688201903,
               47.63829579223815
             ],
             [
               -122.13389128446579,
               47.63782047131512
             ],
             [
               -122.13240802288054,
               47.63783312249837
             ],
             [
               -122.13238388299942,
               47.63829037035086
             ],
             [
               -122.13393688201903,
               47.63829579223815
             ]
           ]
         ]
       },
       "properties": {
         "geometryId": "1"
       }
     }
   ]
}

כל נקודה בפוליגון מוגדרת כזוג אורך ורוחב במערך, ונקודות אלו נמצאות במערך שמוגדר כ-coordinates. ב-Point בשיעור הקודם, ה-coordinates היה מערך שכלל 2 ערכים, רוחב ואורך. עבור Polygon, זהו מערך של מערכים שכל אחד מהם מכיל 2 ערכים, אורך ורוחב.

💁 זכרו, GeoJSON משתמש ב-longitude, latitude עבור נקודות, ולא ב-latitude, longitude.

מערך הקואורדינטות של הפוליגון תמיד כולל ערך אחד יותר ממספר הנקודות בפוליגון, כאשר הערך האחרון זהה לערך הראשון, כדי לסגור את הפוליגון. לדוגמה, עבור מלבן יהיו 5 נקודות.

בתמונה למעלה, ישנו מלבן. הקואורדינטות של הפוליגון מתחילות בפינה השמאלית העליונה ב-47,-122, ואז נעות ימינה ל-47,-121, ואז למטה ל-46,-121, ואז שמאלה ל-46,-122, ואז חזרה לנקודת ההתחלה ב-47,-122. כך יש לפוליגון 5 נקודות - פינה שמאלית עליונה, פינה ימנית עליונה, פינה ימנית תחתונה, פינה שמאלית תחתונה, ואז חזרה לפינה השמאלית העליונה כדי לסגור אותו.

✅ נסו ליצור פוליגון GeoJSON סביב הבית או בית הספר שלכם. השתמשו בכלי כמו GeoJSON.io.

משימה - הגדרת גדר גיאוגרפית

כדי להשתמש בגדר גיאוגרפית ב-Azure Maps, תחילה יש להעלות אותה לחשבון Azure Maps שלכם. לאחר ההעלאה, תקבלו מזהה ייחודי שתוכלו להשתמש בו כדי לבדוק נקודה מול הגדר הגיאוגרפית. כדי להעלות גדרות גיאוגרפיות ל-Azure Maps, יש להשתמש ב-API של המפות. ניתן לקרוא ל-API של Azure Maps באמצעות כלי שנקרא curl.

🎓 Curl הוא כלי שורת פקודה לביצוע בקשות מול נקודות קצה ברשת.

אם אתם משתמשים ב-Linux, macOS, או גרסה עדכנית של Windows 10, ייתכן שכבר יש לכם curl מותקן. הריצו את הפקודה הבאה מהטרמינל או שורת הפקודה כדי לבדוק:
```
curl --version
```
אם אינכם רואים מידע על גרסת curl, תצטרכו להתקין אותו מדף ההורדות של curl.

💁 אם יש לכם ניסיון עם Postman, תוכלו להשתמש בו במקום אם תעדיפו.
צרו קובץ GeoJSON שמכיל פוליגון. תבדקו אותו באמצעות חיישן ה-GPS שלכם, אז צרו פוליגון סביב המיקום הנוכחי שלכם. תוכלו ליצור אחד ידנית על ידי עריכת דוגמת ה-GeoJSON שניתנה למעלה, או להשתמש בכלי כמו GeoJSON.io.

ה-GeoJSON יצטרך לכלול FeatureCollection, שמכיל Feature עם geometry מסוג Polygon.

חובה גם להוסיף אלמנט properties באותה רמה כמו האלמנט geometry, וזה חייב לכלול geometryId:
```
"properties": {
    "geometryId": "1"
}
```
אם אתם משתמשים ב-GeoJSON.io, תצטרכו להוסיף ידנית את הפריט הזה ל-properties הריק, או לאחר הורדת קובץ ה-JSON, או בעורך ה-JSON באפליקציה.

ה-geometryId הזה חייב להיות ייחודי בקובץ זה. תוכלו להעלות מספר גדרות גיאוגרפיות כ-Features מרובים ב-FeatureCollection באותו קובץ GeoJSON, כל עוד לכל אחת יש geometryId שונה. פוליגונים יכולים להיות בעלי אותו geometryId אם הם מועלים מקובץ אחר בזמן אחר.
שמרו את הקובץ בשם geofence.json, ונווטו למיקום שבו הוא נשמר בטרמינל או בקונסולה.
הריצו את פקודת curl הבאה כדי ליצור את הגדר הגיאוגרפית:
```
curl --request POST 'https://atlas.microsoft.com/mapData/upload?api-version=1.0&dataFormat=geojson&subscription-key=<subscription_key>' \
     --header 'Content-Type: application/json' \
     --include \
     --data @geofence.json
```
החליפו את <subscription_key> ב-API key של חשבון Azure Maps שלכם.

ה-URL משמש להעלאת נתוני מפה דרך ה-API https://atlas.microsoft.com/mapData/upload. הקריאה כוללת פרמטר api-version כדי לציין איזו גרסת API של Azure Maps להשתמש, כדי לאפשר שינוי ה-API לאורך זמן תוך שמירה על תאימות לאחור. פורמט הנתונים שמועלה מוגדר כ-geojson.

זה יריץ את בקשת ה-POST ל-API ההעלאה ויחזיר רשימת כותרות תגובה שכוללת כותרת בשם location.
```
content-type: application/json
location: https://us.atlas.microsoft.com/mapData/operations/1560ced6-3a80-46f2-84b2-5b1531820eab?api-version=1.0
x-ms-azuremaps-region: West US 2
x-content-type-options: nosniff
strict-transport-security: max-age=31536000; includeSubDomains
x-cache: CONFIG_NOCACHE
date: Sat, 22 May 2021 21:34:57 GMT
content-length: 0
```
🎓 כאשר קוראים לנקודת קצה ברשת, ניתן להעביר פרמטרים לקריאה על ידי הוספת ? ואחריו זוגות מפתח-ערך כ-key=value, כשהזוגות מופרדים על ידי &.
Azure Maps לא מעבד את זה מיד, אז תצטרכו לבדוק אם בקשת ההעלאה הסתיימה על ידי שימוש ב-URL שניתן בכותרת location. בצעו בקשת GET למיקום זה כדי לראות את הסטטוס. תצטרכו להוסיף את מפתח המנוי שלכם לסוף ה-URL של location על ידי הוספת &subscription-key=<subscription_key> לסוף, כשהמפתח <subscription_key> מוחלף ב-API key של חשבון Azure Maps שלכם. הריצו את הפקודה הבאה:
```
curl --request GET '<location>&subscription-key=<subscription_key>'
```
החליפו את <location> בערך של כותרת location, ואת <subscription_key> ב-API key של חשבון Azure Maps שלכם.
בדקו את הערך של status בתגובה. אם הוא לא Succeeded, חכו דקה ונסו שוב.
ברגע שהסטטוס חוזר כ-Succeeded, הסתכלו על ה-resourceLocation מהתגובה. זה מכיל פרטים על המזהה הייחודי (המכונה UDID) עבור אובייקט ה-GeoJSON. ה-UDID הוא הערך אחרי metadata/, ולא כולל את ה-api-version. לדוגמה, אם ה-resourceLocation היה:
```
{
  "resourceLocation": "https://us.atlas.microsoft.com/mapData/metadata/7c3776eb-da87-4c52-ae83-caadf980323a?api-version=1.0"
}
```
אז ה-UDID יהיה 7c3776eb-da87-4c52-ae83-caadf980323a.

שמרו עותק של ה-UDID הזה כי תצטרכו אותו כדי לבדוק את הגדר הגיאוגרפית.

בדיקת נקודות מול גדר גיאוגרפית

לאחר שהפוליגון הועלה ל-Azure Maps, תוכלו לבדוק נקודה כדי לראות אם היא נמצאת בתוך או מחוץ לגדר הגיאוגרפית. עושים זאת על ידי ביצוע בקשת API ברשת, תוך העברת ה-UDID של הגדר הגיאוגרפית, והרוחב והאורך של הנקודה לבדיקה.

כאשר מבצעים בקשה זו, ניתן גם להעביר ערך שנקרא searchBuffer. ערך זה מציין ל-API של המפות כמה להיות מדויק בעת החזרת תוצאות. הסיבה לכך היא ש-GPS אינו מדויק לחלוטין, ולעיתים מיקומים יכולים להיות שגויים במטרים ואף יותר. ברירת המחדל עבור ה-search buffer היא 50 מטר, אך ניתן להגדיר ערכים בין 0 ל-500 מטר.

כאשר תוצאות מוחזרות מקריאת ה-API, אחד החלקים בתוצאה הוא distance, שנמדד לנקודה הקרובה ביותר על קצה הגדר הגיאוגרפית, עם ערך חיובי אם הנקודה מחוץ לגדר הגיאוגרפית, ושלילי אם היא בתוך הגדר הגיאוגרפית. אם מרחק זה קטן מה-search buffer, המרחק האמיתי מוחזר במטרים, אחרת הערך הוא 999 או -999. 999 אומר שהנקודה מחוץ לגדר הגיאוגרפית ביותר מה-search buffer, -999 אומר שהיא בתוך הגדר הגיאוגרפית ביותר מה-search buffer.

בתמונה למעלה, לגדר הגיאוגרפית יש search buffer של 50 מטר.

נקודה במרכז הגדר הגיאוגרפית, הרבה בתוך ה-search buffer, יש לה מרחק של -999.
נקודה הרבה מחוץ ל-search buffer יש לה מרחק של 999.
נקודה בתוך הגדר הגיאוגרפית ובתוך ה-search buffer, 6 מטר מהגדר הגיאוגרפית, יש לה מרחק של 6 מטר.
נקודה מחוץ לגדר הגיאוגרפית ובתוך ה-search buffer, 39 מטר מהגדר הגיאוגרפית, יש לה מרחק של 39 מטר.

חשוב לדעת את המרחק לקצה הגדר הגיאוגרפית, ולשלב זאת עם מידע נוסף כמו קריאות GPS אחרות, מהירות ונתוני כבישים כאשר מקבלים החלטות בהתבסס על מיקום רכב.

לדוגמה, דמיינו קריאות GPS שמראות שרכב נוסע לאורך כביש שמסתיים ליד גדר גיאוגרפית. אם ערך GPS יחיד אינו מדויק וממקם את הרכב בתוך הגדר הגיאוגרפית, למרות שאין גישה לרכב, ניתן להתעלם ממנו.

בתמונה למעלה, יש גדר גיאוגרפית מעל חלק מקמפוס מיקרוסופט. הקו האדום מראה משאית שנוסעת לאורך כביש 520, עם עיגולים שמייצגים את קריאות ה-GPS. רוב הקריאות מדויקות ונמצאות לאורך כביש 520, אך ישנה קריאה אחת לא מדויקת בתוך הגדר הגיאוגרפית. אין אפשרות שהקריאה הזו נכונה - אין כבישים שמאפשרים למשאית לסטות פתאום מכביש 520 לתוך הקמפוס ואז לחזור לכביש 520. הקוד שבודק את הגדר הגיאוגרפית יצטרך לקחת בחשבון את הקריאות הקודמות לפני שיפעל על תוצאות הבדיקה של הגדר הגיאוגרפית.

✅ אילו נתונים נוספים הייתם צריכים לבדוק כדי לוודא אם קריאת GPS יכולה להיחשב נכונה?

משימה - בדיקת נקודות מול גדר גיאוגרפית

התחילו בבניית כתובת URL לשאילתת ה-API של הרשת. הפורמט הוא:
```
https://atlas.microsoft.com/spatial/geofence/json?api-version=1.0&deviceId=gps-sensor&subscription-key=<subscription-key>&udid=<UDID>&lat=<lat>&lon=<lon>
```
החליפו <subscription_key> במפתח ה-API של חשבון Azure Maps שלכם.

החליפו <UDID> ב-UDID של הגדר הגיאוגרפית מהמשימה הקודמת.

החליפו <lat> ו-<lon> בקווי הרוחב והאורך שברצונכם לבדוק.

כתובת URL זו משתמשת ב-API https://atlas.microsoft.com/spatial/geofence/json כדי לבצע שאילתה על גדר גיאוגרפית שהוגדרה באמצעות GeoJSON. היא מכוונת לגרסת API 1.0. הפרמטר deviceId נדרש וצריך להיות שם המכשיר שממנו מגיעים קווי הרוחב והאורך.

ברירת המחדל של מרחק החיפוש היא 50 מטרים, ואתם יכולים לשנות זאת על ידי העברת פרמטר נוסף של searchBuffer=<distance>, כאשר <distance> הוא מרחק החיפוש במטרים, בין 0 ל-500.
השתמשו ב-curl כדי לבצע בקשת GET לכתובת URL זו:
```
curl --request GET '<URL>'
```
💁 אם אתם מקבלים קוד תגובה של BadRequest, עם שגיאה של:
```
Invalid GeoJSON: All feature properties should contain a geometryId, which is used for identifying the geofence.
```
אז ה-GeoJSON שלכם חסר את החלק properties עם geometryId. תצטרכו לתקן את ה-GeoJSON שלכם, ואז לחזור על השלבים לעיל כדי להעלות מחדש ולקבל UDID חדש.
התגובה תכיל רשימה של geometries, אחת לכל פוליגון שהוגדר ב-GeoJSON ששימש ליצירת הגדר הגיאוגרפית. לכל גיאומטריה יש 3 שדות מעניינים: distance, nearestLat ו-nearestLon.
```
{
    "geometries": [
        {
            "deviceId": "gps-sensor",
            "udId": "7c3776eb-da87-4c52-ae83-caadf980323a",
            "geometryId": "1",
            "distance": 999.0,
            "nearestLat": 47.645875,
            "nearestLon": -122.142713
        }
    ],
    "expiredGeofenceGeometryId": [],
    "invalidPeriodGeofenceGeometryId": []
}
```
- nearestLat ו-nearestLon הם קווי הרוחב והאורך של נקודה על קצה הגדר הגיאוגרפית הקרובה ביותר למיקום הנבדק.
- distance הוא המרחק מהמיקום הנבדק לנקודה הקרובה ביותר על קצה הגדר הגיאוגרפית. מספרים שליליים מציינים בתוך הגדר הגיאוגרפית, חיוביים מחוץ לה. ערך זה יהיה פחות מ-50 (מרחק החיפוש המוגדר כברירת מחדל), או 999.
חזרו על פעולה זו מספר פעמים עם מיקומים בתוך ומחוץ לגדר הגיאוגרפית.

שימוש בגדרות גיאוגרפיות מקוד ללא שרת

כעת תוכלו להוסיף טריגר חדש לאפליקציית Functions שלכם כדי לבדוק את נתוני אירועי ה-GPS של IoT Hub מול הגדר הגיאוגרפית.

קבוצות צרכנים

כפי שתזכרו משיעורים קודמים, IoT Hub מאפשר לכם להפעיל מחדש אירועים שהתקבלו על ידי ההאב אך לא עובדו. אבל מה יקרה אם מספר טריגרים יתחברו? איך הוא ידע מי מהם עיבד אילו אירועים?

התשובה היא שהוא לא יכול! במקום זאת, תוכלו להגדיר מספר חיבורים נפרדים לקרוא אירועים, וכל אחד מהם יכול לנהל את הפעלת ההודעות שלא נקראו. אלה נקראים קבוצות צרכנים. כאשר אתם מתחברים לנקודת הקצה, תוכלו לציין לאיזו קבוצת צרכנים אתם רוצים להתחבר. כל רכיב באפליקציה שלכם יתחבר לקבוצת צרכנים שונה.

באופן תיאורטי, עד 5 אפליקציות יכולות להתחבר לכל קבוצת צרכנים, וכולן יקבלו הודעות כשהן מגיעות. מומלץ שיהיה רק יישום אחד שמתחבר לכל קבוצת צרכנים כדי להימנע מעיבוד כפול של הודעות, ולהבטיח שכאשר מפעילים מחדש כל ההודעות בתור יעובדו כראוי. לדוגמה, אם הפעלתם את אפליקציית Functions שלכם באופן מקומי וגם הפעלתם אותה בענן, שתיהן יעבדו הודעות, מה שיוביל לאחסון כפול של blobs בחשבון האחסון.

אם תבדקו את קובץ function.json עבור טריגר IoT Hub שיצרתם בשיעור קודם, תראו את קבוצת הצרכנים בסעיף הטריגר של Event Hub:

"consumerGroup": "$Default"

כאשר אתם יוצרים IoT Hub, אתם מקבלים את קבוצת הצרכנים $Default שנוצרת כברירת מחדל. אם אתם רוצים להוסיף טריגר נוסף, תוכלו להוסיף זאת באמצעות קבוצת צרכנים חדשה.

💁 בשיעור זה, תשתמשו בפונקציה שונה כדי לבדוק את הגדר הגיאוגרפית מזו ששימשה לאחסון נתוני ה-GPS. זאת כדי להראות כיצד להשתמש בקבוצות צרכנים ולהפריד את הקוד כדי להקל על הקריאה וההבנה. באפליקציה ייצור יש דרכים רבות שבהן תוכלו לארכיטקט את זה - לשים את שניהם בפונקציה אחת, להשתמש בטריגר על חשבון האחסון כדי להפעיל פונקציה לבדוק את הגדר הגיאוגרפית, או להשתמש במספר פונקציות. אין 'דרך נכונה', זה תלוי בשאר האפליקציה שלכם ובצרכים שלכם.

משימה - יצירת קבוצת צרכנים חדשה

הריצו את הפקודה הבאה כדי ליצור קבוצת צרכנים חדשה בשם geofence עבור ה-IoT Hub שלכם:
```
az iot hub consumer-group create --name geofence \
                                 --hub-name <hub_name>
```
החליפו <hub_name> בשם שהשתמשתם בו עבור ה-IoT Hub שלכם.
אם אתם רוצים לראות את כל קבוצות הצרכנים עבור IoT Hub, הריצו את הפקודה הבאה:
```
az iot hub consumer-group list --output table \
                               --hub-name <hub_name>
```
החליפו <hub_name> בשם שהשתמשתם בו עבור ה-IoT Hub שלכם. זה יציג את כל קבוצות הצרכנים.
```
Name      ResourceGroup
--------  ---------------
$Default  gps-sensor
geofence  gps-sensor
```

💁 כאשר הרצתם את מוניטור האירועים של IoT Hub בשיעור קודם, הוא התחבר לקבוצת הצרכנים $Default. זו הסיבה שלא יכולתם להריץ את מוניטור האירועים ואת טריגר האירועים. אם אתם רוצים להריץ את שניהם, תוכלו להשתמש בקבוצות צרכנים אחרות עבור כל אפליקציות הפונקציות שלכם, ולשמור את $Default עבור מוניטור האירועים.

משימה - יצירת טריגר IoT Hub חדש

הוסיפו טריגר אירוע IoT Hub חדש לאפליקציית gps-trigger שלכם שיצרתם בשיעור קודם. קראו לפונקציה זו geofence-trigger.

⚠️ תוכלו להתייחס להוראות ליצירת טריגר אירוע IoT Hub מפרויקט 2, שיעור 5 אם צריך.
הגדירו את מחרוזת החיבור של IoT Hub בקובץ function.json. הקובץ local.settings.json משותף בין כל הטריגרים באפליקציית הפונקציות.
עדכנו את הערך של consumerGroup בקובץ function.json כדי להתייחס לקבוצת הצרכנים החדשה geofence:
```
"consumerGroup": "geofence"
```
תצטרכו להשתמש במפתח המנוי של חשבון Azure Maps שלכם בטריגר זה, אז הוסיפו ערך חדש לקובץ local.settings.json בשם MAPS_KEY.
הריצו את אפליקציית הפונקציות כדי לוודא שהיא מתחברת ומעבדת הודעות. הטריגר iot-hub-trigger מהשיעור הקודם ירוץ גם הוא ויעלה blobs לאחסון.
כדי להימנע מקריאות GPS כפולות באחסון blobs, תוכלו לעצור את אפליקציית הפונקציות שרצה בענן. כדי לעשות זאת, השתמשו בפקודה הבאה:
```
az functionapp stop --resource-group gps-sensor \
                    --name <functions_app_name>
```
החליפו <functions_app_name> בשם שהשתמשתם בו עבור אפליקציית הפונקציות שלכם.

תוכלו להפעיל אותה מחדש מאוחר יותר עם הפקודה הבאה:
```
az functionapp start --resource-group gps-sensor \
                    --name <functions_app_name>
```
החליפו <functions_app_name> בשם שהשתמשתם בו עבור אפליקציית הפונקציות שלכם.

משימה - בדיקת הגדר הגיאוגרפית מהטריגר

בשיעור קודם השתמשתם ב-curl כדי לבצע שאילתה על גדר גיאוגרפית ולבדוק אם נקודה נמצאת בפנים או בחוץ. תוכלו לבצע בקשת רשת דומה מתוך הטריגר שלכם.

כדי לבצע שאילתה על הגדר הגיאוגרפית, אתם צריכים את ה-UDID שלה. הוסיפו ערך חדש לקובץ local.settings.json בשם GEOFENCE_UDID עם ערך זה.
פתחו את קובץ __init__.py מהטריגר החדש geofence-trigger.
הוסיפו את הייבוא הבא לראש הקובץ:
```
import json
import os
import requests
```
חבילת requests מאפשרת לכם לבצע קריאות API ברשת. ל-Azure Maps אין SDK עבור Python, ולכן תצטרכו לבצע קריאות API ברשת כדי להשתמש בו מקוד Python.
הוסיפו את שתי השורות הבאות לתחילת המתודה main כדי לקבל את מפתח המנוי של Maps:
```
maps_key = os.environ['MAPS_KEY']
geofence_udid = os.environ['GEOFENCE_UDID']    
```
בתוך הלולאה for event in events, הוסיפו את הקוד הבא כדי לקבל את קווי הרוחב והאורך מכל אירוע:
```
event_body = json.loads(event.get_body().decode('utf-8'))
lat = event_body['gps']['lat']
lon = event_body['gps']['lon']
```
קוד זה ממיר את ה-JSON מגוף האירוע למילון, ואז שולף את lat ו-lon משדה gps.
כאשר משתמשים ב-requests, במקום לבנות כתובת URL ארוכה כמו שעשיתם עם curl, תוכלו להשתמש רק בחלק של כתובת ה-URL ולהעביר את הפרמטרים כמילון. הוסיפו את הקוד הבא כדי להגדיר את כתובת ה-URL לקריאה ולהגדיר את הפרמטרים:
```
url = 'https://atlas.microsoft.com/spatial/geofence/json'

params = {
    'api-version': 1.0,
    'deviceId': 'gps-sensor',
    'subscription-key': maps_key,
    'udid' : geofence_udid,
    'lat' : lat,
    'lon' : lon
}
```
הפריטים במילון params יתאימו לזוגות המפתח-ערך שהשתמשתם בהם כאשר קראתם ל-API ברשת באמצעות curl.
הוסיפו את השורות הבאות של קוד כדי לקרוא ל-API ברשת:
```
response = requests.get(url, params=params)
response_body = json.loads(response.text)
```
זה קורא לכתובת ה-URL עם הפרמטרים, ומחזיר אובייקט תגובה.

הוסיפו את הקוד הבא מתחת לזה:

distance = response_body['geometries'][0]['distance']

if distance == 999:
    logging.info('Point is outside geofence')
elif distance > 0:
    logging.info(f'Point is just outside geofence by a distance of {distance}m')
elif distance == -999:
    logging.info(f'Point is inside geofence')
else:
    logging.info(f'Point is just inside geofence by a distance of {distance}m')

קוד זה מניח גיאומטריה אחת, ושולף את המרחק מאותה גיאומטריה יחידה. לאחר מכן הוא רושם הודעות שונות בהתבסס על המרחק.

הריצו את הקוד הזה. תראו בפלט הלוגים אם קואורדינטות ה-GPS נמצאות בתוך או מחוץ לגדר הגיאוגרפית, עם מרחק אם הנקודה נמצאת בתוך 50 מטרים. נסו את הקוד הזה עם גדרות גיאוגרפיות שונות בהתבסס על מיקום חיישן ה-GPS שלכם, נסו להזיז את החיישן (לדוגמה, מחובר ל-WiFi מטלפון נייד, או עם קואורדינטות שונות במכשיר IoT וירטואלי) כדי לראות את השינוי.
כאשר אתם מוכנים, פרסו את הקוד הזה לאפליקציית הפונקציות שלכם בענן. אל תשכחו לפרוס את הגדרות האפליקציה החדשות.

⚠️ תוכלו להתייחס להוראות להעלאת הגדרות אפליקציה מפרויקט 2, שיעור 5 אם צריך.

⚠️ תוכלו להתייחס להוראות לפריסת אפליקציית הפונקציות שלכם מפרויקט 2, שיעור 5 אם צריך.

💁 תוכלו למצוא את הקוד הזה בתיקיית code/functions.

🚀 אתגר

בשיעור זה הוספתם גדר גיאוגרפית אחת באמצעות קובץ GeoJSON עם פוליגון יחיד. תוכלו להעלות מספר פוליגונים בו-זמנית, כל עוד יש להם ערכי geometryId שונים בחלק properties.

נסו להעלות קובץ GeoJSON עם מספר פוליגונים והתאימו את הקוד שלכם כדי למצוא איזה פוליגון קואורדינטות ה-GPS קרובות אליו או בתוכו.

מבחן לאחר השיעור

סקירה ולימוד עצמי

קראו עוד על גדרות גיאוגרפיות ועל כמה מהשימושים שלהן בעמוד Geofencing בויקיפדיה.
קראו עוד על API הגדרות גיאוגרפיות של Azure Maps בתיעוד Microsoft Azure Maps Spatial - Get Geofence.
קראו עוד על קבוצות צרכנים בתיעוד Features and terminology in Azure Event Hubs - Event consumers documentation on Microsoft docs.

משימה

שלחו התראות באמצעות Twilio

כתב ויתור:
מסמך זה תורגם באמצעות שירות תרגום מבוסס בינה מלאכותית Co-op Translator. למרות שאנו שואפים לדיוק, יש לקחת בחשבון שתרגומים אוטומטיים עשויים להכיל שגיאות או אי דיוקים. המסמך המקורי בשפתו המקורית צריך להיחשב כמקור סמכותי. עבור מידע קריטי, מומלץ להשתמש בתרגום מקצועי על ידי אדם. איננו נושאים באחריות לאי הבנות או לפרשנויות שגויות הנובעות משימוש בתרגום זה.

README.md Unescape Escape