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 از دستور GRPC Transcoding استفاده می کند.

درخواست بدن

بدنه درخواست حاوی داده هایی با ساختار زیر است:

نمایندگی 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 نباید بیشتر از 50 باشد.
  • حاصل ضرب تعداد مبدا × تعداد مقصد در هر صورت نباید بیشتر از 625 باشد.
  • اگر routingPreference روی TRAFFIC_AWARE_OPTIMAL تنظیم شده باشد، حاصل ضرب تعداد مبدا × تعداد مقصدها نباید بیشتر از 100 باشد.
  • اگر TravelMode روی TRANSIT تنظیم شده باشد، حاصل ضرب تعداد مبدا × تعداد مقصدها نباید بیشتر از 100 باشد.
destinations[]

object ( RouteMatrixDestination )

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

travel Mode

enum ( RouteTravelMode )

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

routing Preference

enum ( RoutingPreference )

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

departure Time

string ( Timestamp format)

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

مهر زمانی در قالب RFC3339 UTC "Zulu"، با وضوح نانوثانیه و حداکثر نه رقم کسری. مثال‌ها: "2014-10-02T15:01:23Z" و "2014-10-02T15:01:23.045123456Z" .

arrival Time

string ( Timestamp format)

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

مهر زمانی در قالب RFC3339 UTC "Zulu"، با وضوح نانوثانیه و حداکثر نه رقم کسری. مثال‌ها: "2014-10-02T15:01:23Z" و "2014-10-02T15:01:23.045123456Z" .

language Code

string

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

region Code

string

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

units

enum ( Units )

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

extra Computations[]

enum ( ExtraComputation )

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

traffic Model

enum ( TrafficModel )

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

transit Preferences

object ( TransitPreferences )

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

بدن پاسخگو

حاوی اطلاعات مسیر محاسبه شده برای یک جفت مبدا/مقصد در 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 )

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

distance Meters

integer

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

duration

string ( Duration format)

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

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

static Duration

string ( Duration format)

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

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

travel Advisory

object ( RouteTravelAdvisory )

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

fallback Info

object ( FallbackInfo )

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

localized Values

object ( LocalizedValues )

نمایش متنی خصوصیات RouteMatrixElement .

origin Index

integer

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

destination Index

integer

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

RouteMatrixOrigin

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

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

object ( Waypoint )

مورد نیاز. نقطه راه مبدأ

route Modifiers

object ( RouteModifiers )

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

RouteMatrixDestination

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

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

object ( Waypoint )

مورد نیاز. ایستگاه بین راهی مقصد

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

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

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

RouteMatrixElementCondition

وضعیت مسیر در حال برگشت.

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

Localized Values

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

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

object ( LocalizedText )

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

duration

object ( LocalizedText )

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

static Duration

object ( LocalizedText )

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

transit Fare

object ( LocalizedText )

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