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

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

• יצירת מסלול: הגדרת מסלול יחיד באמצעות נקודת הקצה create.
• יצירת קבוצת מסלולים: אפשר להגדיר כמה מסלולים בבקשה אחת באמצעות נקודת הקצה batchCreate.
• יצירת מסלול עם נקודות ציון ביניים: אפשר להגדיר מסלול עם עד 25 נקודות ציון ביניים.
• שימוש במאפיינים מותאמים אישית של מסלולים: אפשר להוסיף עד 10 צמדים מותאמים אישית של מפתח/ערך למסלולים למטרות ארגוניות.

יצירת מסלול

כדי ליצור מסלול, שולחים בקשת 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 תווים, ולהכיל רק תווים אלפאנומריים. אם לא מספקים מזהה, המערכת יוצרת מזהה ייחודי למסלול שנבחר.

אזהרה: selectedRouteId לא תומך בתווים מיוחדים, כולל קווים תחתונים ונקודתיים. אם מוסיפים תו מיוחד ל-selectedRouteId, ה-API מחזיר שגיאה INVALID_ARGUMENT.

בדוגמת הקוד הבאה מוצג המבנה של בקשת 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"