إنشاء مسارات محدّدة

توضّح هذه الصفحة كيفية إنشاء طرق وإضافة سمات مخصّصة باستخدام 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، ستعرض واجهة برمجة التطبيقات الخطأ 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"

عند النجاح، تعرض واجهة برمجة التطبيقات المرجع 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.

يجب أن يكون نص الطلب عنصر 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"

عند النجاح، تعرض واجهة برمجة التطبيقات استجابة تحتوي على مصفوفة من موارد 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"