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

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

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

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

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

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

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

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

روش ComputeRouteMatrix ازطریق نقطه پایانی Routes Preferred 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 ارسال کنید. باید از پروتکل TLS استفاده کنید.

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

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

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

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

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

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