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

توضّح هذه الصفحة كيفية إنشاء الطرق وإضافة سمات مخصّصة باستخدام 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 يتضمّن المعلومات التالية:
  • The origin للطريق المحدّد
  • The 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. تتيح لك نقطة النهاية هذه تحديد ما يصل إلى 1000 طريق في طلب واحد.

أرسِل طلب 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"

استخدام سمات الطريق المخصّصة

لتحسين إدارة المسارات وتحليل البيانات ضمن بيانات إدارة الطرق، يتضمّن الكائن 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"