إعداد Route Optimization API

يوضّح هذا المستند الخطوات التي يجب اتّباعها لبدء استخدام Route Optimization API.

المتطلبات الأساسية

يساعدك هذا الإجراء في إعداد حساب على Google Cloud ومشروع على السحابة الإلكترونية مع تفعيل الفوترة. يجب أيضًا أن تكون على دراية بكيفية تحصيل الرسوم منك مقابل استخدام Route Optimization API.

1. راجِع الفوترة وتكلفة الاستخدام في استخدام Route Optimization API والفوترة.

2. تأكَّد من أنّ لديك حساب على Google Cloud.

   سجِّل الدخول إلى Google Cloud Console

3. تأكَّد من أنّ لديك مشروعًا على Google Cloud تم تفعيل الفوترة فيه.

   انتقِل إلى صفحة "الفوترة"
1. اختَر مشروعك لفتح صفحة الفوترة.

2. في صفحة الفوترة:

   • إذا كانت الفوترة مفعَّلة للمشروع المحدّد، وكان لديك حساب فوترة واحد فقط، ستفتح صفحة الفوترة.
   • إذا كانت لديك حسابات فوترة متعددة، اختَر الانتقال إلى حساب الفوترة المرتبط للاطّلاع على تفاصيل حساب الفوترة المرتبط بالمشروع.
   • إذا كان هناك حساب فوترة ولكنّه غير مرتبط بالمشروع، سيُطلب منك ربط حساب فوترة بالمشروع.
   • إذا لم يكن هناك حساب فوترة، أو إذا أردت إنشاء حساب فوترة جديد، اختَر إدارة حسابات الفوترة لإنشاء حساب فوترة جديد. لمزيد من المعلومات، يُرجى الاطّلاع على مقالة إنشاء حساب فوترة جديد للخدمة الذاتية على Google Cloud.

تفعيل واجهة برمجة التطبيقات

قبل استخدام Route Optimization API، عليك استخدام وحدة تحكّم Google Cloud أو الأمر gcloud لتفعيلها في مشروعك على Google Cloud.

لتفعيل واجهة برمجة التطبيقات:

gcloud services enable \
    --project "PROJECT" \
    "routeoptimization.googleapis.com"

تتطلّب منتجات "منصة خرائط Google" أن تتضمّن طلبات البيانات من واجهة برمجة التطبيقات رمز OAuth مميّزًا لمنع الاستخدام غير المصرّح به.

إنشاء رمز OAuth مميّز

تتيح واجهة Route Optimization API استخدام بروتوكول OAuth 2.0 للمصادقة. تتيح Google سيناريوهات OAuth 2.0 الشائعة، مثل سيناريوهات خادم الويب.

يوضّح هذا المستند كيفية تمرير رمز OAuth المميّز إلى طلب بيانات من Route Optimization API في بيئة التطوير. لمزيد من المعلومات حول استخدام OAuth في بيئة التشغيل الفعلي، يُرجى الاطّلاع على طرق المصادقة في Google.

يمكنك طلب بيانات من Google Maps API مباشرةً من خلال إرسال طلبات بيانات من واجهة برمجة التطبيقات إلى الخادم، أو يمكنك استخدام مكتبات العملاء لتبسيط الرمز البرمجي. توفّر "خرائط Google" مكتبات برامج للغات Go وJava وNode.js وPython. لمزيد من المعلومات، يُرجى الاطّلاع على مكتبات عملاء Route Optimization API.

نظرة عامة على OAuth

يمكنك إنشاء رموز الدخول وإدارتها باستخدام OAuth بعدة طرق حسب بيئة النشر.

يمكنك استخدام OAuth 2.0 للتفاعلات بين الخوادم بين تطبيقك وخدمة Google. في هذا السيناريو، يمكنك استخدام حساب خدمة مرتبط بتطبيقك بدلاً من مستخدم فردي. يمكنك إرسال طلبات بيانات من واجهة برمجة التطبيقات باستخدام حساب الخدمة بدون إشراك المستخدمين مباشرةً. لمزيد من المعلومات عن طرق المصادقة، يُرجى الاطّلاع على طرق المصادقة في Google.

بدلاً من ذلك، يمكنك دمج Route Optimization API في تطبيق متوافق مع Android أو iOS للأجهزة الجوّالة. لمزيد من المعلومات حول استخدام OAuth وإدارة رموز الدخول لبيئات النشر المختلفة، يُرجى الاطّلاع على استخدام OAuth 2.0 للوصول إلى Google APIs.

نطاقات OAuth

لاستخدام OAuth مع Route Optimization API، يجب منح رمز OAuth المميّز النطاق التالي:

https://www.googleapis.com/auth/cloud-platform

ضبط الأدوار

يوفّر هذا المستند معلومات عن أدوار وأذونات "إدارة الهوية وإمكانية الوصول" (IAM) لخدمة Route Optimization. تتيح لك "إدارة الهوية وإمكانية الوصول" منح إذن وصول دقيق إلى موارد محدّدة في Route Optimization وتساعد في منع الوصول إلى موارد أخرى. تتيح لك "إدارة الهوية وإمكانية الوصول" تطبيق مبدأ الأمان المستنِد إلى الحدّ الأدنى من الأذونات المميّزة، والذي ينص على أنّه لا يجب أن يحصل أي مستخدم على أذونات أكثر مما يحتاج إليه فعليًا.

عندما يطلب مستخدم أساسي (مستخدم أو مجموعة أو حساب خدمة) واجهة برمجة تطبيقات Google Cloud، يجب أن يكون لدى هذا المستخدم الأساسي أذونات "إدارة الهوية وإمكانية الوصول" المناسبة لاستخدام المورد. لمنح مستخدم أساسي الأذونات المطلوبة، يمكنك منحه دورًا في "إدارة الهوية وإمكانية الوصول".

للتعرّف على كيفية إدارة أذونات الوصول في Google Cloud بشكل عام، يُرجى الاطّلاع على نظرة عامة على "إدارة الهوية وإمكانية الوصول".

أدوار "إدارة الهوية وإمكانية الوصول" المحدّدة مسبقًا للسماح للمستخدمين الأساسيين بالوصول إلى Route Optimization هي:

• Route Optimization Editor (roles/routeoptimization.editor): يمنح المستخدم أو حساب الخدمات إذن الوصول للقراءة والكتابة إلى موارد "تحسين المسار" في المشروع. ويشمل ذلك إمكانية استدعاء OptimizeTours وBatchOptimizeTours، بالإضافة إلى استرداد العمليات الطويلة باستخدام GetOperation.
• ‫Route Optimization Viewer (roles/routeoptimization.viewer): يمنح هذا الدور إذنًا بالقراءة فقط لموارد Route Optimization في المشروع. يتيح هذا الدور إمكانية طلب OptimizeTours والوصول إلى العمليات الطويلة باستخدام GetOperation.

gcloud projects add-iam-policy-binding PROJECT \
  --member user:someone@example.com \
  --role roles/routeoptimization.editor

لمزيد من المعلومات، يُرجى الاطّلاع على كيفية منح دور في "إدارة الهوية وإمكانية الوصول" باستخدام وحدة تحكّم Google Cloud.

مثال: تجربة طلبات بيانات من واجهة برمجة التطبيقات REST API في بيئة التطوير المحلية

إذا لم تكن لديك بيئة تنشئ الرموز المميّزة وأردت تجربة Route Optimization API باستخدام رمز OAuth مميّز، اتّبِع الإجراءات الواردة في هذا القسم.

يوضّح هذا المثال كيفية استخدام رمز OAuth المميّز الذي توفّره بيانات الاعتماد التلقائية للتطبيق (ADC) لإجراء الطلب. لمزيد من المعلومات حول استخدام ADC لطلب Google APIs من خلال مكتبات العملاء، يُرجى الاطّلاع على المصادقة باستخدام مكتبات العملاء.

استخدِم إجراء REST التالي لأغراض التطوير أو الاختبار فقط، وليس لأغراض الإنتاج.

المتطلبات الأساسية

قبل إجراء طلب REST باستخدام ADC، استخدِم واجهة سطر الأوامر (CLI) في gcloud لتقديم بيانات الاعتماد إلى ADC:

1. ثبِّت واجهة سطر الأوامر (CLI) في gcloud وافتحها. لمزيد من المعلومات، يُرجى الاطّلاع على مقالة تثبيت gcloud CLI.

2. المصادقة باستخدام واجهة سطر الأوامر (CLI) في gcloud:

   gcloud auth application-default login

3. أكمِل عملية تسجيل الدخول لحفظ بيانات الاعتماد في ملف بيانات الاعتماد المحلي الذي تستخدمه ADC.

لمزيد من المعلومات، يُرجى الاطّلاع على مقالة إعداد ADC لبيئة تطوير محلية.

إرسال طلب REST

في هذا المثال، يتم تمرير عنوانَي طلب:

• مرِّر رمز OAuth المميّز في العنوان Authorization باستخدام الأمر التالي لإنشاء الرمز المميّز:

  gcloud auth application-default print-access-token

  يحتوي الرمز المميّز الذي تم إرجاعه على نطاق https://www.googleapis.com/auth/cloud-platform.

• أدخِل رقم تعريف أو اسم مشروعك على Google Cloud الذي تم تفعيل الفوترة فيه في العنوان X-Goog-User-Project.

لطلب Route Optimization API باستخدام رمز OAuth المميّز، أكمِل الخطوات التالية:

1. في عينة التعليمات البرمجية التالية، استبدِل PROJECT_NUMBER_OR_ID برقم مشروعك على Google Cloud أو رقم تعريفه:

   curl -X POST 'https://routeoptimization.googleapis.com/v1/projects/PROJECT_NUMBER_OR_ID:optimizeTours' \
   -H "Content-Type: application/json" \
   -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
   --data-binary @- << EOM
   {
   "model": {
   "shipments": [
     {
       "pickups": [
         {
           "arrivalLocation": {
             "latitude": 37.73881799999999,
             "longitude": -122.4161
           }
         }
       ],
       "deliveries": [
         {
           "arrivalLocation": {
             "latitude": 37.79581,
             "longitude": -122.4218856
           }
         }
       ]
     }
   ],
   "vehicles": [
     {
       "startLocation": {
         "latitude": 37.73881799999999,
         "longitude": -122.4161
       },
       "endLocation": {
         "latitude": 37.73881799999999,
         "longitude": -122.4161
       }
     }
   ],
   "globalStartTime": "2023-01-13T16:00:00-08:00",
   "globalEndTime": "2023-01-14T16:00:00-08:00"
   }
   }
   EOM
   

2. لنسخ الأمر curl، انقر على نسخ في عينة التعليمات البرمجية.

3. الصِق الأمر في نافذة المحطة الطرفية، ثم شغِّله.

الردّ هو عنصر JSON:

{
  "routes": [
    {
      "vehicleStartTime": "2023-01-14T00:00:00Z",
      "vehicleEndTime": "2023-01-14T00:39:22Z",
      "visits": [
        {
          "isPickup": true,
          "startTime": "2023-01-14T00:00:00Z",
          "detour": "0s"
        },
        {
          "startTime": "2023-01-14T00:19:53Z",
          "detour": "0s"
        }
      ],
      "transitions": [
        {
          "travelDuration": "0s",
          "waitDuration": "0s",
          "totalDuration": "0s",
          "startTime": "2023-01-14T00:00:00Z"
        },
        {
          "travelDuration": "1193s",
          "travelDistanceMeters": 9007,
          "waitDuration": "0s",
          "totalDuration": "1193s",
          "startTime": "2023-01-14T00:00:00Z"
        },
        {
          "travelDuration": "1169s",
          "travelDistanceMeters": 9546,
          "waitDuration": "0s",
          "totalDuration": "1169s",
          "startTime": "2023-01-14T00:19:53Z"
        }
      ],
      "metrics": {
        "performedShipmentCount": 1,
        "travelDuration": "2362s",
        "waitDuration": "0s",
        "delayDuration": "0s",
        "breakDuration": "0s",
        "visitDuration": "0s",
        "totalDuration": "2362s",
        "travelDistanceMeters": 18553
      }
    }
  ],
  "metrics": {
    "aggregatedRouteMetrics": {
      "performedShipmentCount": 1,
      "travelDuration": "2362s",
      "waitDuration": "0s",
      "delayDuration": "0s",
      "breakDuration": "0s",
      "visitDuration": "0s",
      "totalDuration": "2362s",
      "travelDistanceMeters": 18553
    },
    "usedVehicleCount": 1,
    "earliestVehicleStartTime": "2023-01-14T00:00:00Z",
    "latestVehicleEndTime": "2023-01-14T00:39:22Z"
  }
}

تحديد المشاكل وحلّها

إذا عرض طلبك رسالة خطأ تفيد بأنّ واجهة برمجة التطبيقات هذه لا تتيح استخدام بيانات اعتماد المستخدم النهائي، يُرجى الاطّلاع على تحديد المشاكل وحلّها في إعداد "بيانات الاعتماد التلقائية للتطبيق".