Update selected routes

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

• تعديل مسار: يمكنك تعديل تفاصيل مسار واحد باستخدام نقطة النهاية patch.
• تعديلات مجمَّعة للمسارات: يمكنك تعديل تفاصيل مسارات متعدّدة في طلب واحد باستخدام نقطة النهاية batchUpdate.

تعديل مسار

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

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

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

يتطلّب تعديل شكل المسار (dynamicRoute) إعادة التحقّق منه. يُسمح بتعديل الشكل عندما يكون المسار في حالتَي STATE_RUNNING أو STATE_INVALID، ويتم رفض التعديلات إذا كان المسار في حالتَي STATE_VALIDATING أو STATE_DELETING. لمزيد من المعلومات، يُرجى الاطّلاع على حالات التحقّق من الصحة وحالات المسار. يُسمح بتعديل البيانات الوصفية، مثل displayName أو routeAttributes، في جميع الحالات باستثناء 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"
}

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

لتعديل مسارات متعدّدة في طلب واحد، استخدِم 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 أو كائن 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"
    },
    {
      "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"
    }
  ]
}