Update selected routes

توضّح هذه الصفحة كيفية تعديل المسارات التي سبق لك إنشاؤها باستخدام Roads Selection API:

تعديل مسار

لتعديل مسار، أرسِل طلب PATCH إلى نقطة النهاية patch:

https://roads.googleapis.com/selection/v1/projects/PROJECT_NUMBER/selectedRoutes/SELECTED_ROUTE_ID?updateMask=UPDATE_MASK

يجب أن يكون نص الطلب عنصر JSON يحتوي على حقول SelectedRoute المطلوب تعديلها. تشمل الحقول القابلة للتعديل displayName وrouteAttributes وdynamicRoute وdynamicRouting (سواء كان المسار ثابتًا أو ديناميكيًا). عند تعديل نقاط المسار (dynamicRoute)، يجب تقديم عنصر dynamicRoute بالكامل (نقطة الانطلاق والوجهة ونقاط المسار المتوسطة). لا يمكن تعديل الحقول الفرعية جزئيًا. لا يمكن تعديل حقول النظام المخصّصة للقراءة فقط، مثل name وcreateTime وstate. تحتفظ البيانات السابقة في BigQuery بالبيانات الخاصة بالنقاط على المسار السابقة والمعدَّلة ضمن selectedRouteId نفسه. إذا كنت بحاجة إلى بيانات سابقة منفصلة، أنشئ مسارًا جديدًا بدلاً من إجراء تعديل.

يؤدي تعديل النقاط على المسار (dynamicRoute) إلى إعادة التحقّق من صحة المسار. يتم تعديل الحقلَين static_route_geometry وroad_segment_ids في جدول BigQuery‏ routes_status وفقًا لذلك.

يُسمح بتعديل النقاط على المسار عندما يكون المسار في الحالة STATE_RUNNING أو STATE_INVALID، ويتم رفضه إذا كان المسار في الحالة STATE_VALIDATING أو STATE_DELETING. لمزيد من المعلومات، يُرجى الاطّلاع على حالات التحقّق والمسار. يُسمح بتعديل البيانات الوصفية، مثل displayName أو routeAttributes أو dynamicRouting في جميع الولايات باستثناء STATE_DELETING.

تعرض عيّنة التعليمات البرمجية التالية بنية طلب PATCH إلى نقطة النهاية patch:

curl -X PATCH -d '{
    "dynamicRoute": {
      "origin": {
        "latitude": 38.5817,
        "longitude": -121.4944
      },
      "destination": {
        "latitude": 38.5449,
        "longitude": -121.7405
      }
    }
  }' \
-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/"\
"SELECTED_ROUTE_ID?updateMask=dynamicRoute"

في حال نجاح الطلب، تعرض واجهة برمجة التطبيقات مورد SelectedRoute المعدَّل:

{
  "name": "projects/PROJECT_NUMBER/selectedRoutes/SELECTED_ROUTE_ID",
  "dynamicRoute": {
    "origin": {
      "latitude": 38.5817,
      "longitude": -121.4944
    },
    "destination": {
      "latitude": 38.5449,
      "longitude": -121.7405
    }
  },
  "createTime": "2026-08-14T20:58:41.345418Z",
  "state": "STATE_VALIDATING",
  "dynamicRouting": TRUE_OR_FALSE
}

تعديلات مجمَّعة للمسارات

لتعديل مسارات متعددة في طلب واحد، استخدِم نقطة النهاية batchUpdate. تتيح لك نقطة النهاية هذه تعديل ما يصل إلى 1,000 مسار في طلب واحد. التعديلات المجمَّعة هي تعديلات ذرية: إذا تعذّر التحقّق من صحة أي مسار في الطلب أو تعذّر تعديله، لن يتم تعديل أي مسارات في المجموعة.

أرسِل طلب POST إلى نقطة النهاية batchUpdate:

https://roads.googleapis.com/selection/v1/projects/PROJECT_NUMBER/selectedRoutes:batchUpdate

يجب أن يكون نص الطلب عبارة عن عنصر JSON يحتوي على مصفوفة requests. كل عنصر ضمن هذه المصفوفة هو UpdateSelectedRouteRequest يحدّد المسار name، وupdateMask اختياري على مستوى السلعة، وحقول selectedRoute المطلوب تعديلها.

‫updateMask هي مَعلمة اختيارية تحدّد قائمة الحقول التي سيتم تعديلها (displayName أو routeAttributes أو dynamicRouting أو عنصر dynamicRoute بالكامل). يشير الإعداد updateMask=* إلى استبدال كامل. يمكن تحديد updateMask داخل كل عنصر فردي في requests، أو نقله إلى المستوى الأعلى من نص الطلب المجمّع ليتم تطبيقه على جميع المسارات المعدَّلة في الدفعة. في حال حذف updateMask، سيتم تعديل جميع الحقول القابلة للتعديل التي تم ملؤها في الطلب. إذا تم ضبط السمة updateMask على مستوى الدفعة ومستوى السلعة، يجب أن تكون القيمتان متطابقتَين. يؤدي تحديد أقنعة متعارضة إلى حدوث خطأ INVALID_ARGUMENT.

تعرض عيّنة التعليمات البرمجية التالية بنية طلب POST إلى نقطة النهاية batchUpdate:

curl -X POST -d '{
    "requests": [
      {
        "selectedRoute": {
          "name": "projects/PROJECT_NUMBER/selectedRoutes/SELECTED_ROUTE_ID_1",
          "displayName": "DISPLAY_NAME_1",
          "dynamicRoute": {
            "origin": {"latitude": 37.5, "longitude": -122.1},
            "destination": {"latitude": 37.8, "longitude": -122.5}
          }
        },
        "updateMask": "displayName,dynamicRoute"
      },
      {
        "selectedRoute": {
          "name": "projects/PROJECT_NUMBER/selectedRoutes/SELECTED_ROUTE_ID_2",
          "displayName": "DISPLAY_NAME_2",
          "dynamicRoute": {
            "origin": {"latitude": 37.5, "longitude": -122.1},
            "destination": {"latitude": 37.8, "longitude": -122.5}
          }
        },
        "updateMask": "displayName,dynamicRoute"
      }
    ]}' \
-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:batchUpdate"

في حال نجاح الطلب، تعرض واجهة برمجة التطبيقات استجابة تحتوي على مصفوفة من موارد SelectedRoute التي تم تعديلها:

{
  "selectedRoutes": [
    {
      "name": "projects/PROJECT_NUMBER/selectedRoutes/SELECTED_ROUTE_ID_1",
      "displayName": "DISPLAY_NAME_1",
      "dynamicRoute": {
        "origin": {
          "latitude": 37.5,
          "longitude": -122.1
        },
        "destination": {
          "latitude": 37.8,
          "longitude": -122.5
        }
      },
      "createTime": "2026-08-14T20:58:41.345418Z",
      "state": "STATE_VALIDATING",
      "dynamicRouting": TRUE_OR_FALSE
    },
    {
      "name": "projects/PROJECT_NUMBER/selectedRoutes/SELECTED_ROUTE_ID_2",
      "displayName": "DISPLAY_NAME_2",
      "dynamicRoute": {
        "origin": {
          "latitude": 37.5,
          "longitude": -122.1
        },
        "destination": {
          "latitude": 37.8,
          "longitude": -122.5
        }
      },
      "createTime": "2026-08-14T20:58:41.345418Z",
      "state": "STATE_VALIDATING",
      "dynamicRouting": TRUE_OR_FALSE
    }
  ]
}