Method: computeRouteMatrix

لیستی از مبدا و مقصد را دریافت کرده و جریانی حاوی اطلاعات مسیر برای هر ترکیبی از مبدا و مقصد را برمی‌گرداند.

نکته: این روش مستلزم آن است که شما یک ماسک فیلد پاسخ را در ورودی مشخص کنید. می‌توانید ماسک فیلد پاسخ را با استفاده از پارامتر URL $fields یا fields یا با استفاده از هدر HTTP/gRPC X-Goog-FieldMask (به پارامترها و هدرهای URL موجود مراجعه کنید) ارائه دهید. مقدار، لیستی از مسیرهای فیلد است که با کاما از هم جدا شده‌اند. برای آشنایی با نحوه ساخت مسیرهای فیلد، به این مستندات دقیق مراجعه کنید.

مثلاً در این روش:

  • ماسک فیلد تمام فیلدهای موجود (برای بررسی دستی): X-Goog-FieldMask: *
  • ماسک فیلد از مدت زمان مسیر، مسافت‌ها، وضعیت عنصر، شرایط و شاخص‌های عنصر (یک نمونه تنظیمات تولید): X-Goog-FieldMask: originIndex,destinationIndex,status,condition,distanceMeters,duration

بسیار مهم است که status در ماسک فیلد خود وارد کنید، زیرا در غیر این صورت همه پیام‌ها بدون مشکل به نظر می‌رسند. گوگل استفاده از ماسک فیلد پاسخ با کاراکترهای وایلدکارد ( * ) را توصیه نمی‌کند، زیرا:

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

درخواست HTTP

POST https://routes.googleapis.com/distanceMatrix/v2:computeRouteMatrix

این URL از سینتکس Transcoding در gRPC استفاده می‌کند.

درخواست بدنه

بدنه درخواست شامل داده‌هایی با ساختار زیر است:

نمایش JSON 
{
  "origins": [
    {
      object (RouteMatrixOrigin)
    }
  ],
  "destinations": [
    {
      object (RouteMatrixDestination)
    }
  ],
  "travelMode": enum (RouteTravelMode),
  "routingPreference": enum (RoutingPreference),
  "departureTime": string,
  "arrivalTime": string,
  "languageCode": string,
  "regionCode": string,
  "units": enum (Units),
  "extraComputations": [
    enum (ExtraComputation)
  ],
  "trafficModel": enum (TrafficModel),
  "transitPreferences": {
    object (TransitPreferences)
  }
}
فیلدها
origins[]

object ( RouteMatrixOrigin )

الزامی. آرایه‌ای از مبداها، که سطرهای ماتریس پاسخ را تعیین می‌کند. چندین محدودیت اندازه برای تعداد مبداها و مقصدها اعمال می‌شود:

  • مجموع تعداد مبداها + تعداد مقاصد مشخص شده به صورت placeId یا address نباید بیشتر از ۵۰ باشد.
  • حاصلضرب تعداد مبداها × تعداد مقاصد در هیچ حالتی نباید بیشتر از ۶۲۵ باشد.
  • اگر routingPreference روی TRAFFIC_AWARE_OPTIMAL تنظیم شده باشد، حاصلضرب تعداد مبداها × تعداد مقصدها نباید بیشتر از ۱۰۰ باشد.
  • اگر travelMode روی TRANSIT تنظیم شده باشد، حاصلضرب تعداد مبداها × تعداد مقصدها نباید بیشتر از ۱۰۰ باشد.
destinations[]

object ( RouteMatrixDestination )

الزامی. آرایه‌ای از مقصدها که ستون‌های ماتریس پاسخ را تعیین می‌کند.

travelMode

enum ( RouteTravelMode )

اختیاری. نحوه حمل و نقل را مشخص می‌کند.

routingPreference

enum ( RoutingPreference )

اختیاری. نحوه محاسبه مسیر را مشخص می‌کند. سرور تلاش می‌کند از تنظیمات مسیریابی انتخاب شده برای محاسبه مسیر استفاده کند. اگر تنظیمات مسیریابی منجر به خطا یا تأخیر طولانی مدت شود، خطا بازگردانده می‌شود. می‌توانید این گزینه را فقط زمانی مشخص کنید که travelMode DRIVE یا TWO_WHEELER باشد، در غیر این صورت درخواست با شکست مواجه می‌شود.

departureTime

string ( Timestamp format)

اختیاری. زمان حرکت. اگر این مقدار را تنظیم نکنید، این مقدار به طور پیش‌فرض برابر با زمانی است که درخواست را انجام داده‌اید. توجه: فقط زمانی می‌توانید departureTime در گذشته مشخص کنید که RouteTravelMode روی TRANSIT تنظیم شده باشد.

از RFC 3339 استفاده می‌کند، که در آن خروجی تولید شده همیشه به صورت Z-normalized خواهد بود و از ارقام کسری ۰، ۳، ۶ یا ۹ استفاده می‌کند. آفست‌های غیر از "Z" نیز پذیرفته می‌شوند. مثال‌ها: "2014-10-02T15:01:23Z" ، "2014-10-02T15:01:23.045123456Z" یا "2014-10-02T15:01:23+05:30" .

arrivalTime

string ( Timestamp format)

اختیاری. زمان رسیدن. توجه: فقط زمانی قابل تنظیم است که RouteTravelMode روی TRANSIT تنظیم شده باشد. می‌توانید departureTime یا arrivalTime مشخص کنید، اما نمی‌توانید هر دو را با هم داشته باشید.

از RFC 3339 استفاده می‌کند، که در آن خروجی تولید شده همیشه به صورت Z-normalized خواهد بود و از ارقام کسری ۰، ۳، ۶ یا ۹ استفاده می‌کند. آفست‌های غیر از "Z" نیز پذیرفته می‌شوند. مثال‌ها: "2014-10-02T15:01:23Z" ، "2014-10-02T15:01:23.045123456Z" یا "2014-10-02T15:01:23+05:30" .

languageCode

string

اختیاری. کد زبان BCP-47، مانند "en-US" یا "sr-Latn". برای اطلاعات بیشتر، به شناسه محلی یونیکد مراجعه کنید. برای لیست زبان‌های پشتیبانی شده به پشتیبانی زبان مراجعه کنید. وقتی این مقدار را ارائه نمی‌دهید، زبان نمایش از محل اولین مبدا استنباط می‌شود.

regionCode

string

اختیاری. کد منطقه، که به عنوان یک مقدار دو کاراکتری ccTLD ("دامنه سطح بالا") مشخص شده است. برای اطلاعات بیشتر به دامنه‌های سطح بالای کد کشور مراجعه کنید.

units

enum ( Units )

اختیاری. واحدهای اندازه‌گیری برای فیلدهای نمایش را مشخص می‌کند.

extraComputations[]

enum ( ExtraComputation )

اختیاری. فهرستی از محاسبات اضافی که ممکن است برای تکمیل درخواست استفاده شوند. توجه: این محاسبات اضافی ممکن است فیلدهای اضافی را در پاسخ برگردانند. این فیلدهای اضافی همچنین باید در ماسک فیلدی که قرار است در پاسخ برگردانده شود، مشخص شوند.

trafficModel

enum ( TrafficModel )

اختیاری. فرضیات مورد استفاده هنگام محاسبه زمان ترافیک را مشخص می‌کند. این تنظیم بر مقدار برگردانده شده در فیلد مدت زمان در RouteMatrixElement تأثیر می‌گذارد که شامل زمان پیش‌بینی‌شده ترافیک بر اساس میانگین‌های تاریخی است. TrafficModel فقط برای درخواست‌هایی در دسترس است که RoutingPreference روی TRAFFIC_AWARE_OPTIMAL و RouteTravelMode را روی DRIVE تنظیم کرده‌اند. اگر ترافیک درخواست شود و TrafficModel مشخص نشده باشد، پیش‌فرض روی BEST_GUESS است.

transitPreferences

object ( TransitPreferences )

اختیاری. تنظیماتی را مشخص می‌کند که بر مسیر برگشتی برای مسیرهای TRANSIT تأثیر می‌گذارند. توجه: فقط زمانی می‌توانید transitPreferences مشخص کنید که RouteTravelMode روی TRANSIT تنظیم شده باشد.

بدنه پاسخ

شامل اطلاعات مسیر محاسبه‌شده برای یک جفت مبدا/مقصد در v2.computeRouteMatrix API است. این پروتو می‌تواند به کلاینت ارسال شود.

در صورت موفقیت، بدنه پاسخ شامل داده‌هایی با ساختار زیر است:

نمایش JSON 
{
  "status": {
    object (Status)
  },
  "condition": enum (RouteMatrixElementCondition),
  "distanceMeters": integer,
  "duration": string,
  "staticDuration": string,
  "travelAdvisory": {
    object (RouteTravelAdvisory)
  },
  "fallbackInfo": {
    object (FallbackInfo)
  },
  "localizedValues": {
    object (LocalizedValues)
  },
  "originIndex": integer,
  "destinationIndex": integer
}
فیلدها
status

object ( Status )

کد وضعیت خطا برای این عنصر.

condition

enum ( RouteMatrixElementCondition )

نشان می‌دهد که آیا مسیر پیدا شده است یا خیر. مستقل از وضعیت.

distanceMeters

integer

مسافت طی شده در مسیر، بر حسب متر.

duration

string ( Duration format)

مدت زمان لازم برای پیمایش مسیر. اگر routingPreference روی TRAFFIC_UNAWARE تنظیم کنید، این مقدار با staticDuration برابر است. اگر routingPreference روی TRAFFIC_AWARE یا TRAFFIC_AWARE_OPTIMAL تنظیم کنید، این مقدار با در نظر گرفتن شرایط ترافیک محاسبه می‌شود.

مدت زمانی بر حسب ثانیه با حداکثر نه رقم کسری که به ' s ' ختم می‌شود. مثال: "3.5s" .

staticDuration

string ( Duration format)

مدت زمان سفر در طول مسیر بدون در نظر گرفتن شرایط ترافیک.

مدت زمانی بر حسب ثانیه با حداکثر نه رقم کسری که به ' s ' ختم می‌شود. مثال: "3.5s" .

travelAdvisory

object ( RouteTravelAdvisory )

اطلاعات تکمیلی در مورد مسیر. به عنوان مثال: اطلاعات محدودیت‌ها و اطلاعات عوارض

fallbackInfo

object ( FallbackInfo )

در برخی موارد، زمانی که سرور قادر به محاسبه مسیر با تنظیمات داده شده برای این جفت مبدا/مقصد خاص نیست، ممکن است به استفاده از حالت محاسبه متفاوتی بازگردد. هنگامی که از حالت جایگزین استفاده می‌شود، این فیلد حاوی اطلاعات دقیقی در مورد پاسخ جایگزین است. در غیر این صورت، این فیلد تنظیم نشده است.

localizedValues

object ( LocalizedValues )

نمایش متنی ویژگی‌های RouteMatrixElement .

originIndex

integer

شاخص مبتنی بر صفر مبدا در درخواست.

destinationIndex

integer

شاخص مبتنی بر صفر مقصد در درخواست.

RouteMatrixOrigin

یک مبدا واحد برای ComputeRouteMatrixRequest

نمایش JSON 
{
  "waypoint": {
    object (Waypoint)
  },
  "routeModifiers": {
    object (RouteModifiers)
  }
}
فیلدها
waypoint

object ( Waypoint )

الزامی. نقطه مسیر مبدا

routeModifiers

object ( RouteModifiers )

اختیاری. اصلاح‌کننده‌ها برای هر مسیری که این را به عنوان مبدا در نظر می‌گیرد

RouteMatrixDestination

یک مقصد واحد برای ComputeRouteMatrixRequest

نمایش JSON 
{
  "waypoint": {
    object (Waypoint)
  }
}
فیلدها
waypoint

object ( Waypoint )

الزامی. نقطه مسیر مقصد

محاسبات اضافی

محاسبات اضافی که باید هنگام تکمیل درخواست انجام شوند.

انوم‌ها
EXTRA_COMPUTATION_UNSPECIFIED استفاده نمی‌شود. درخواست‌های حاوی این مقدار با شکست مواجه می‌شوند.
TOLLS اطلاعات عوارض برای عنصر(های) ماتریس.

شرط عنصر RouteMatrix

وضعیت مسیری که قرار است برگردانده شود.

انوم‌ها
ROUTE_MATRIX_ELEMENT_CONDITION_UNSPECIFIED فقط زمانی استفاده می‌شود که status عنصر OK نباشد.
ROUTE_EXISTS مسیری پیدا شد و اطلاعات مربوطه برای عنصر پر شد.
ROUTE_NOT_FOUND هیچ مسیری یافت نشد. فیلدهای حاوی اطلاعات مسیر، مانند distanceMeters یا duration ، در عنصر پر نخواهند شد.

مقادیر محلی

نمایش متنی ویژگی‌های خاص.

نمایش JSON 
{
  "distance": {
    object (LocalizedText)
  },
  "duration": {
    object (LocalizedText)
  },
  "staticDuration": {
    object (LocalizedText)
  },
  "transitFare": {
    object (LocalizedText)
  }
}
فیلدها
distance

object ( LocalizedText )

مسافت طی شده به صورت متنی نمایش داده می‌شود.

duration

object ( LocalizedText )

مدت زمان نمایش داده شده به صورت متنی با در نظر گرفتن شرایط ترافیک. توجه: اگر اطلاعات ترافیک درخواست نشده باشد، این مقدار همان مقدار staticDuration است.

staticDuration

object ( LocalizedText )

مدت زمان نمایش داده شده به صورت متنی بدون در نظر گرفتن شرایط ترافیک.

transitFare

object ( LocalizedText )

کرایه حمل و نقل عمومی به صورت متنی نمایش داده می‌شود.