راه‌اندازی Route Optimization API

این سند مراحلی را که باید برای شروع استفاده از Route Optimization API انجام دهید شرح می‌دهد.

پیش‌نیازها

این رویه شما را در راه‌اندازی کردن «حساب Google Cloud» و پروژه Google Cloud با صورت‌حساب فعال راهنمایی می‌کند. همچنین باید با نحوه کسر هزینه برای استفاده از Route Optimization API آشنا باشید.

1. مرور صورت‌حساب و هزینه استفاده در استفاده و صورت‌حساب Route Optimization API.

2. تأیید کنید که حساب Google Cloud دارید.

   به سیستم کنسول Google Cloud وارد شوید

3. تأیید کنید که پروژه Google Cloud با صورت‌حساب فعال دارید.

   رفتن به صفحه «صورت‌حساب»
1. پروژه‌تان را انتخاب کنید تا صفحه صورت‌حساب باز شود.

2. در صفحه صورت‌حساب:

   • اگر صورت‌حساب ازقبل برای پروژه انتخاب‌شده فعال شده باشد و فقط یک حساب صورت‌حساب داشته باشید، صفحه صورت‌حساب باز می‌شود.
   • اگر چند حساب صورت‌حساب دارید، رفتن به حساب صورت‌حساب پیوندشده را انتخاب کنید تا جزئیات مربوط به حساب صورت‌حساب مرتبط با پروژه را ببینید.
   • اگر حساب صورت‌حساب وجود داشته باشد اما با پروژه مرتبط نباشد، از شما خواسته می‌شود حساب صورت‌حساب را به پروژه پیوند دهید.
   • اگر حساب صورت‌حساب وجود ندارد، یا می‌خواهید حساب صورت‌حساب جدیدی ایجاد کنید، مدیریت حساب‌های صورت‌حساب را انتخاب کنید تا حساب صورت‌حساب جدیدی ایجاد کنید. برای اطلاعات بیشتر، ایجاد حساب Cloud Billing سلف سرویس جدید را ببینید.

فعال کردن میانای برنامه‌سازی کاربردی

قبل‌از اینکه بتوانید از Route Optimization API استفاده کنید، باید از کنسول Google Cloud یا فرمان gcloud برای فعال کردن آن در پروژه Google Cloud خود استفاده کنید.

برای فعال کردن میانای برنامه‌سازی کاربردی:

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

محصولات Google Maps Platform برای جلوگیری از استفاده غیرمجاز، به فراخوانی‌های میانای برنامه‌سازی کاربردی نیاز دارند تا شامل یک کد OAuth باشند.

ایجاد کد OAuth

‫Route Optimization API از OAuth 2.0 برای اصالت‌سنجی پشتیبانی می‌کند. Google از سناریوهای رایج OAuth 2.0، مثل سناریوهای سرور وب، پشتیبانی می‌کند.

این سند نحوه ارسال کردن یک کد OAuth به فراخوانی Route Optimization API در محیط توسعه نرم‌افزار را شرح می‌دهد. برای اطلاعات بیشتر درباره استفاده از OAuth در محیط تولید، به روش‌های اصالت‌سنجی در Google مراجعه کنید.

می‌توانید با ارسال درخواست‌های میانای برنامه‌سازی کاربردی به سرور، مستقیماً میاناهای برنامه‌سازی کاربردی Google Maps را فراخوانی کنید، یا می‌توانید از کتابخانه‌های کارخواه برای ساده کردن کدتان استفاده کنید. ‫Google Maps کتابخانه‌های کارخواه را برای Go،‏ Java،‏ Node.js، و Python ارائه می‌دهد. برای اطلاعات بیشتر، به کتابخانه‌های کارخواه Route Optimization API مراجعه کنید.

نمای کلی OAuth

می‌توانید کد دسترسی را با OAuth به چند روش بسته به محیط استقرار خود ایجاد و مدیریت کنید.

می‌توانید از OAuth 2.0 برای تعاملات سروربه‌سرور بین برنامه‌تان و سرویس Google استفاده کنید. برای این سناریو، از حساب سرویسی استفاده می‌کنید که به‌جای کاربر فردی، با برنامه‌تان مرتبط است. می‌توانید بااستفاده از حساب سرویس و بدون دخالت مستقیم کاربران، درخواست‌های API ارسال کنید. برای اطلاعات بیشتر درباره روش‌های اصالت‌سنجی، به روش‌های اصالت‌سنجی در Google مراجعه کنید.

یا می‌توانید Route Optimization API را در برنامه تلفن همراه Android یا iOS ادغام کنید. برای اطلاعات بیشتر درباره استفاده از OAuth و مدیریت کردن کد دسترسی برای محیط‌های استقرار مختلف، استفاده از OAuth 2.0 برای دسترسی به Google API را ببینید.

دامنه‌های OAuth

برای استفاده از OAuth با Route Optimization API، باید دامنه زیر را به کد OAuth اختصاص دهید:

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

پیکربندی نقش‌ها

این سند اطلاعاتی درباره نقش‌ها و اجازه‌های «مدیریت هویت و دسترسی‌ها» (IAM) برای «بهینه‌سازی مسیر» ارائه می‌دهد. IAM به شما امکان می‌دهد دسترسی جزئی به منابع خاص «بهینه‌سازی مسیر» اعطا کنید و به جلوگیری از دسترسی به منابع دیگر کمک می‌کند. ‫IAM به شما امکان می‌دهد اصل امنیتی حداقل امتیاز را اعمال کنید، که بیان می‌کند هیچ‌کس نباید اجازه‌هایی بیشتر از آنچه واقعاً نیاز دارد داشته باشد.

وقتی‌که یک اصلی (کاربر، گروه، یا حساب سرویس) یک Google Cloud API را فراخوانی می‌کند، آن اصلی باید اجازه‌های IAM مناسب را برای استفاده از منبع داشته باشد. برای دادن اجازه‌های لازم به یک اصلی، نقش IAM را به آن اصلی اعطا می‌کنید.

برای آشنایی با مدیریت دسترسی در Google Cloud به‌طور کلی، نمای کلی IAM را ببینید.

نقش‌های IAM ازپیش‌تعریف‌شده برای اجازه دادن به مدیران برای دسترسی به Route Optimization عبارتند از:

• Route Optimization Editor (roles/routeoptimization.editor): به کاربر یا حساب سرویس‌ها اجازه دسترسی خواندن و نوشتن به منابع «بهینه‌سازی مسیر» در پروژه را می‌دهد. این شامل توانایی فراخوانی OptimizeTours و BatchOptimizeTours، و همچنین بازیابی عملیات طولانی‌مدت بااستفاده از GetOperation می‌شود.
• Route Optimization Viewer (roles/routeoptimization.viewer): دسترسی فقط خواندنی به منابع «بهینه‌سازی مسیر» در پروژه را اعطا می‌کند. این نقش امکان فراخوانی OptimizeTours و دسترسی به «عملیات طولانی‌مدت» را بااستفاده از GetOperation فراهم می‌کند.

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

برای اطلاعات بیشتر، اعطای نقش IAM بااستفاده از کنسول Google Cloud را ببینید.

مثال: فراخوانی‌های REST API را در محیط توسعه محلی‌تان امتحان کنید

اگر محیطی ندارید که توکن تولید کند و می‌خواهید Route Optimization API را با توکن OAuth امتحان کنید، از روال این بخش استفاده کنید.

این مثال نحوه استفاده از کد OAuth ارائه‌شده توسط اعتبارنامه‌های پیش‌فرض برنامه (ADC) را برای برقراری تماس شرح می‌دهد. برای اطلاعات بیشتر درباره استفاده از ADC برای فراخوانی Google APIs با کتابخانه‌های کارخواه، به اصالت‌سنجی بااستفاده از کتابخانه‌های کارخواه مراجعه کنید.

از روال REST زیر فقط برای توسعه یا آزمایش استفاده کنید، نه برای تولید.

پیش‌نیازها

قبل‌از اینکه درخواست REST بااستفاده از ADC ایجاد کنید، از gcloud CLI برای ارائه اعتبارنامه به ADC استفاده کنید:

1. gcloud CLI را نصب و مقداردهی اولیه کنید. برای اطلاعات بیشتر، به نصب gcloud CLI مراجعه کنید.

2. با gcloud CLI اصالت‌سنجی کنید:

   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"
  }
}

عیب‌یابی

اگر درخواستتان پیام خطایی برمی‌گرداند که می‌گوید این میانای برنامه‌سازی کاربردی از اعتبارنامه کاربر نهایی پشتیبانی نمی‌کند، به عیب‌یابی راه‌اندازی ADC مراجعه کنید.