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

במאמר הזה מוסבר איך ליצור מסלולים ולהוסיף מאפיינים בהתאמה אישית באמצעות 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 תווים, והתווים התקינים הם a-z,‏ A-Z,‏ 0-9,‏ - או _. אם לא תספקו מזהה, המערכת תיצור מזהה ייחודי למסלול שנבחר.

יצירת מסלול קבוע (ברירת מחדל)

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

אפשר להגדיר את השדה הבוליאני dynamicRouting בגוף הבקשה כדי לציין אם המסלול קבוע (false, ברירת המחדל) או דינמי (true).

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

יצירת מסלול דינמי

אפשר גם ליצור נתיב דינמי על ידי הגדרת השדה dynamicRouting לערך true. הגיאומטריה של המסלול יכולה להשתנות בהתאם למצב התנועה, כי פלטפורמת המסלולים של Google מוצאת את המסלול הכי טוב בכל פעם.

דוגמת הקוד הבאה מראה את המבנה של בקשת POST לcreate של מסלול דינמי:

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

דוגמת הקוד הבאה מראה את המבנה של תגובה תקינה מנקודת הקצה 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",
  "dynamicRouting": true
}

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

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

  • סינון התראות 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 לנקודת הקצה (endpoint) של 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 שנוצרו.

דוגמת הקוד הבאה מראה את המבנה של תגובה מנקודת קצה (endpoint) של 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",
      "dynamicRouting": false
    },
    {
      "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
        }
      },
      "createTime": "CREATE_TIME_2",
      "state": "STATE_VALIDATING",
      "dynamicRouting": false
    }
  ]
}