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

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

تعرض عيّنة التعليمات البرمجية التالية بنية طلب 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"

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

  • فلترة إشعارات 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.

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

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