יצירת מסלולים שנבחרו

במאמר הזה מוסבר איך ליצור מסלולים ולהוסיף מאפיינים מותאמים אישית באמצעות Roads Selection API. המאמר מחולק לקטעים הבאים:

יצירת מסלול

כדי ליצור מסלול, שולחים בקשת POST לנקודת הקצה create.

https://roads.googleapis.com/selection/v1/projects/PROJECT_NUMBER/selectedRoutes?selectedRouteId=SELECTED_ROUTE_ID

גוף הבקשה חייב להיות אובייקט JSON שמגדיר את משאב SelectedRoute. האובייקט הזה מציין את המידע הבא:

  • אובייקט dynamicRoute עם הפרטים הבאים:
    • origin של המסלול שנבחר.
    • destination של המסלול שנבחר.
    • כל intermediates במסלול, שנקראות גם נקודות עצירה.
  • selectedRouteId ייחודי. הערך הזה צריך להיות באורך של 4 עד 63 תווים ולהכיל רק תווים אלפאנומריים. אם לא תספקו מזהה, המערכת תיצור מזהה ייחודי למסלול שנבחר.

בדוגמת הקוד הבאה מוצג המבנה של בקשת POST לנקודת הקצה create.

curl -X POST -d '
    {"dynamic_route": { \
      origin: {latitude: ORIGIN_LATITUDE ,longitude: ORIGIN_LONGITUDE}, \
      destination: {latitude: DESTINATION_LATITUDE, longitude: DESTINATION_LONGITUDE} \
    }}' \' \
  -H 'X-Goog-User-Project: PROJECT_NUMBER' \
  -H 'Content-Type: application/json' \
  -H "Authorization: Bearer ACCESS_TOKEN" \
  "https://roads.googleapis.com/selection/v1/projects/PROJECT_NUMBER/selectedRoutes?selectedRouteId=SELECTED_ROUTE_ID"

אם הפעולה בוצעה ללא שגיאות, ה-API מחזיר את משאב SelectedRoute. התשובה כוללת את selectedRouteId בשדה name. אפשר להשתמש בselectedRouteId כדי לאחזר או למחוק את המשאב SelectedRoute.

בדוגמת הקוד הבאה מוצג המבנה של תגובת נקודת קצה מוצלחת create.

{
  "name": "projects/PROJECT_NUMBER/selectedRoutes/SELECTED_ROUTE_ID",
  "dynamicRoute": {
    "origin": {
      "latitude": ORIGIN_LATITUDE,
      "longitude": ORIGIN_LONGITUDE
    },
    "destination": {
      "latitude": DESTINATION_LATITUDE,
      "longitude": DESTINATION_LONGITUDE
    }
  },
  "createTime": "CREATE_TIME",
  "state": "STATE_VALIDATING"
}

יצירת מסלולים בכמות גדולה

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

שליחת בקשת POST לנקודת הקצה batchCreate:

https://roads.googleapis.com/selection/v1/projects/PROJECT_NUMBER/selectedRoutes:batchCreate

כתובת ה-URL כתובה בתחביר של gRPC Transcoding.

גוף הבקשה חייב להיות אובייקט JSON שמכיל מערך requests. כל אובייקט במערך הזה הוא CreateSelectedRouteRequest שמגדיר משאב SelectedRoute נפרד.

בדוגמת הקוד הבאה אפשר לראות את המבנה של בקשת POST לנקודת הקצה batchCreate:

curl -X POST -d '
    {"requests": [
      {
        "dynamicRoute": {
          "origin": {"latitude": ORIGIN_LATITUDE_1, "longitude": ORIGIN_LONGITUDE_1},
          "destination": {"latitude": DESTINATION_LATITUDE_1, "longitude": DESTINATION_LONGITUDE_1}
        },
        "selectedRouteId": "route-one"
      },
      {
        "dynamicRoute": {
          "origin": {"latitude": ORIGIN_LATITUDE_2, "longitude": ORIGIN_LONGITUDE_2},
          "destination": {"latitude": DESTINATION_LATITUDE_2, "longitude": DESTINATION_LONGITUDE_2}
        },
        "selectedRouteId": "route-two"
      }
    ]}
  ' \
  -H 'X-Goog-User-Project: PROJECT_NUMBER' \
  -H 'Content-Type: application/json' \
  -H "Authorization: Bearer ACCESS_TOKEN" \
  "https://roads.googleapis.com/selection/v1/projects/PROJECT_NUMBER/selectedRoutes:batchCreate"

אם הפעולה בוצעה ללא שגיאות, ה-API מחזיר תגובה שמכילה מערך של משאבי SelectedRoute שנוצרו.

בדוגמת הקוד הבאה מוצג המבנה של תגובת נקודת הקצה batchCreate:

{
  "selectedRoutes": [
    {
      "name": "projects/PROJECT_NUMBER/selectedRoutes/SELECTED_ROUTE_ID_1",
      "dynamicRoute": {
        "origin": {
          "latitude": ORIGIN_LATITUDE_1,
          "longitude": ORIGIN_LONGITUDE_1
        },
        "destination": {
          "latitude": DESTINATION_LATITUDE_1,
          "longitude": DESTINATION_LONGITUDE_1
        }
      },
      "createTime": "CREATE_TIME_1",
      "state": "STATE_VALIDATING"
    },
    {
      "name": "projects/PROJECT_NUMBER/selectedRoutes/SELECTED_ROUTE_ID_2",
      "dynamicRoute": {
        "origin": {
          "latitude": ORIGIN_LATITUDE_2,
          "longitude": ORIGIN_LONGITUDE_2
        },
        "destination": {
          "latitude": DESTINATION_LATITUDE_2,
          "longitude": DESTINATION_LONGITUDE_2
        }
      },
      "intermediates": [],
      "createTime": "CREATE_TIME_2",
      "state": "STATE_VALIDATING"
    }
  ]
}

יצירת מסלול עם נקודות ציון ביניים

כדי ליצור מסלול שעובר דרך נקודות ספציפיות בין נקודת המוצא ליעד, צריך לכלול מערך intermediates באובייקט dynamicRoute בגוף הבקשה. כל רכיב במערך intermediates הוא נקודת ציון שמוגדרת על ידי latitude ו-longitude. מסלול יכול לכלול עד 25 נקודות ציון.

בדוגמת הקוד הבאה אפשר לראות איך יוצרים SelectedRoute עם נקודות ציון ביניים:

curl -X POST -d '
    {"dynamic_route": { \
        "origin": {"latitude": ORIGIN_LATITUDE , "longitude": ORIGIN_LONGITUDE}, \
        "intermediates": [
          {"latitude": INTERMEDIATE_LATITUDE_1, "longitude": INTERMEDIATE_LONGITUDE_1},
          {"latitude": INTERMEDIATE_LATITUDE_2, "longitude": INTERMEDIATE_LONGITUDE_2},
          {"latitude": INTERMEDIATE_LATITUDE_3, "longitude": INTERMEDIATE_LONGITUDE_3}
        ],
        "destination": {"latitude": DESTINATION_LATITUDE, "longitude": DESTINATION_LONGITUDE}}}' \
  -H 'X-Goog-User-Project: PROJECT_NUMBER' \
  -H 'Content-Type: application/json' \
  -H "Authorization: Bearer ACCESS_TOKEN" \
  "https://roads.googleapis.com/selection/v1/projects/PROJECT_NUMBER/selectedRoutes?selectedRouteId=SELECTED_ROUTE_ID"

שימוש במאפיינים מותאמים אישית של מסלולים

כדי לשפר את ניהול המסלולים וניתוח הנתונים ב-Roads Management Insights, האובייקט SelectedRoute כולל את השדה route_attributes.

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

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

אלה כמה דוגמאות למאפייני מסלול שאפשר להשתמש בהם:

  • "road_classification": "highway"
  • "maintenance_zone": "north_district"
  • "event_id": "marathon_2024"
  • "pavement_type": "asphalt"

כשמגדירים את השדה routeAttributes, צריך לפעול לפי ההנחיות הבאות:

  • מפתחות לא יכולים להתחיל בקידומת goog.
  • האורך של כל מפתח וכל ערך לא יכול להיות יותר מ-100 תווים.

אחר כך תוכלו להשתמש בrouteAttributes המותאמים אישית האלה בתובנות לניהול כבישים בדרכים הבאות:

  • סינון התראות Pub/Sub: אפשר להגדיר מסננים במינויים ל-Pub/Sub כדי לקבל עדכונים רק לגבי מסלולים שתואמים למפתחות ספציפיים של מאפיינים ולערכים התואמים שלהם, או לא תואמים להם.
  • לשפר את הניתוח ב-BigQuery: בטבלאות BigQuery, אפשר להשתמש במאפיינים האלה כדי לסנן מסלולים ספציפיים לפי ערך של מאפיין. אפשר גם לקבץ מסלולים לפי מפתח מאפיין ספציפי כדי לבצע ניתוח נתונים ממוקד יותר.

בדוגמת הקוד הבאה אפשר לראות איך יוצרים SelectedRoute עם routeAttributes בהתאמה אישית.

curl -X POST -d '
    {"dynamic_route": { origin: {latitude: ORIGIN_LATITUDE ,longitude: ORIGIN_LONGITUDE}, destination: {latitude: DESTINATION_LATITUDE, longitude: DESTINATION_LONGITUDE}}, route_attributes: {"ATTRIBUTE_KEY":"ATTRIBUTE_VALUE"}}' \
  -H 'X-Goog-User-Project: PROJECT_NUMBER' \
  -H 'Content-Type: application/json' \
  -H "Authorization: Bearer ACCESS_TOKEN" \
  "https://roads.googleapis.com/selection/v1/projects/PROJECT_NUMBER/selectedRoutes?selectedRouteId=SELECTED_ROUTE_ID"