محاسبه ماتریس مسیر

بااستفاده از روش ComputeRouteMatrix در «میانای برنامه‌سازی کاربردی ترجیحی مسیرها»، می‌توانید فاصله و مدت زمان مسیر را برای چندین مبدأ و مقصد محاسبه کنید. ‫ComputeRouteMatrix از هر دو تماس جاری‌سازی gRPC و تماس‌های REST HTTP پشتیبانی می‌کند.

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

روش ComputeRouteMatrix نسبت‌به Distance Matrix API (قدیمی) چندین مزیت دارد:

  • جاری‌سازی امکان می‌دهد عناصر قبل‌از محاسبه کل ماتریس برگردانده شوند و این کار تأخیر را کاهش می‌دهد.
  • ‫ComputeRouteMatrix گزینه‌های دقیقی برای محاسبه ترافیک دارد که به شما امکان می‌دهد درباره مبادله کیفیت-تأخیر تصمیم‌گیری کنید.
  • درخواست‌ها در زیرساخت Google با اولویت بالاتری اجرا می‌شوند که منجر به دردسترس بودن بیشتر می‌شود.
  • می‌توانید اطلاعات مربوط به سمت جاده و جهت سفر را برای ایستگاه‌های بین راه مشخص کنید.
  • می‌توانید درخواست کنید اطلاعات عوارض، همراه با فاصله مسیر و «زمان تخمینی رسیدن» برگردانده شود.

فعال کردن روش ComputeRouteMatrix

قبل‌از اینکه بتوانید از روش ComputeRouteMatrix در کدتان استفاده کنید، باید آن را فعال کنید. برای اطلاعات بیشتر درباره فعال کردن روش‌های Routes Preferred API، به شروع به کار مراجعه کنید.

استفاده از روش ComputeRouteMatrix

روش ComputeRouteMatrix ازطریق نقطه پایانی «مسیرهای ترجیحی» v1 دردسترس است.

برای اطلاعات دقیق‌تر، مستندات زیر را ببینید:

gRPC: https://developers.google.com/maps/documentation/routes_preferred/reference/rpc/google.maps.routes.v1

‫REST: https://developers.google.com/maps/documentation/routes_preferred/reference/rest/v1/TopLevel/computeRouteMatrix

مراحل عمومی زیر نحوه استفاده از gRPC برای فراخوانی روش ComputeRouteMatrix را شرح می‌دهد:

  1. پروتوبافرهای لازم را از مخزن googleapis بررسی کنید:

    https://github.com/googleapis/googleapis/tree/master/google/maps/routes

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

  2. بااستفاده از زبان برگزیده و مجموعه ابزارهای ساخت، کد protobuffer مربوطه را تولید کنید.

  3. درخواستتان را تولید کنید. دو قطعه فراداده الزامی باید همراه با درخواست ارسال شود:

    • X-Goog-Api-Key باید روی کلید میانای API شما تنظیم شود.

    • X-Goog-Fieldmask باید روی فهرست جداشده با کاما از فیلدهایی که از پاسخ نیاز دارید تنظیم شود. برای مثال، X-Goog-FieldMask: originIndex,destinationIndex,duration,distanceMeters,status. می‌توانید از نویسه کارت جوکر (*) برای نشان دادن همه فیلدها استفاده کنید، اما این کار توصیه نمی‌شود. از نویسه گل‌چین برای آزمایش و درک پاسخ «میانای برنامه‌سازی کاربردی» استفاده کنید، اما فیلدهایی را که در پوشش فیلد در کد تولیدتان می‌خواهید به‌طور صریح فهرست کنید.

      برای اطلاعات بیشتر درباره نحوه ساختن رشته پوشش فیلد، به https://github.com/protocolbuffers/protobuf/blob/master/src/google/protobuf/field_mask.proto مراجعه کنید. توجه داشته باشید که غیرفعال کردن فیلدهایی که به آن‌ها نیاز ندارید می‌تواند تأخیر را کاهش دهد زیرا این فیلدها ممکن است به محاسبات بیشتری نیاز داشته باشند. اگر فیلدهای موردنیازتان را مشخص کنید و فیلدهای جدیدی که به محاسبات بیشتری نیاز دارند بعداً اضافه شوند، تأخیر شما ثابت خواهد ماند.

  4. درخواستتان را به routespreferred.googleapis.com:443 ارسال کنید.باید از پروتکل «امنیت لایه انتقال» استفاده کنید.

برای نمونه‌هایی از استفاده از روش ComputeRouteMatrix، به نمونه‌های محاسبه ماتریس مسیر (نسخه بتا) مراجعه کنید.

یکی از ویژگی‌های متمایز روش ComputeRouteMatrix این است که کدهای خطا را می‌توان برای کل جاری‌سازی یا برای عناصر مجزا برگرداند. برای مثال، اگر درخواست بدشکل باشد (مثلاً مبدأ آن صفر باشد)، اتصال جاری‌سازی خطا برمی‌گرداند. بااین‌حال، اگر خطایی فقط برای چند عنصر از جاری‌سازی اعمال شود (برای مثال، تنظیم شناسه مکان نامعتبر برای مبدأ)، فقط عناصر تحت‌تأثیر خطا حاوی کدهای خطا خواهند بود.

عناصر برگردانده‌شده توسط جاری‌سازی تضمین نمی‌شود که به هر ترتیبی برگردانده شوند. به‌همین دلیل، هر عنصر حاوی یک origin_index و یک destination_index است. برای مبدأها و مقصدهای مشخص‌شده در درخواست، مبدأ مسیر برای عنصر داده‌شده معادل origins[origin_index] و مقصد مسیر معادل destinations[destination_index] است. این آرایه‌ها دارای نمایه صفر هستند. ذخیره کردن ترتیب فهرست مبدأ و مقصد مهم است.

درحال محاسبه عوارض

برای اطلاعات درباره محاسبه عوارض، به محاسبه عوارض مراجعه کنید.

برای نمونه‌های محاسبه عوارض، به محاسبه نمونه‌های ماتریس مسیر مراجعه کنید.