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

במאמר הזה מוסבר איך ליצור מסלולים ולהוסיף מאפיינים מותאמים אישית באמצעות 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 '
    {
      "dynamicRoute": {
        "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"
}

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

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

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

curl -X POST -d '
    {
      "dynamicRoute": {
        "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"

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

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

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

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

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

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

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

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

לאחר מכן תוכלו להשתמש בrouteAttributes המותאמים אישית האלה ב-Roads Management Insights (תובנות לניהול כבישים) בדרכים הבאות:

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

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

curl -X POST -d '
    {
    "dynamicRoute": {
      "origin": {
        "latitude": ORIGIN_LATITUDE,
        "longitude": ORIGIN_LONGITUDE
      },
      "destination": {
        "latitude": DESTINATION_LATITUDE,
        "longitude": DESTINATION_LONGITUDE
      }
    },
    "routeAttributes": {
      "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"

יצירת מסלולים באצווה

כדי ליצור כמה מסלולים בבקשה אחת, משתמשים בנקודת הקצה 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": [
        {
          "selectedRoute": {
            "dynamicRoute": {
              "origin": {
                "latitude": ORIGIN_LATITUDE_1,
                "longitude": ORIGIN_LONGITUDE_1
              },
              "destination": {
                "latitude": DESTINATION_LATITUDE_1,
                "longitude": DESTINATION_LONGITUDE_1
              }
            }
          },
          "selectedRouteId": "route-one"
        },
        {
          "selectedRoute": {
            "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"
    }
  ]
}