Wybieranie informacji zwracanych

Gdy wywołujesz metodę, aby obliczać trasę lub macierz tras, musisz określić, jakie informacje chcesz uzyskać, określając pola, które mają się pojawić w odpowiedzi. Nie ma domyślnej listy zwróconych pól. Pominięcie tej listy spowoduje, że metody zwracają błąd.

Listę pól określasz przez utworzenie maski pola odpowiedzi. Następnie przekazuj maskę pola odpowiedzi do metody za pomocą parametru adresu URL $fields lub fields albo nagłówka HTTP lub gRPC X-Goog-FieldMask.

Maskowanie pól to dobra metoda projektowania, która pozwala uniknąć żądań niepotrzebnych danych, co pozwala uniknąć niepotrzebnego czasu przetwarzania i naliczonych opłat.

Więcej informacji o parametrach adresu URL znajdziesz w artykule Parametry systemowe.

Zdefiniuj maskę pola odpowiedzi

Maska pola odpowiedzi to lista ścieżek rozdzielonych przecinkami, z których każda ścieżka wiąże się z unikalnym polem w komunikacie z odpowiedzią. Ścieżka rozpoczyna się od wiadomości z odpowiedzią najwyższego poziomu i używa ścieżki prowadzącej do określonego pola rozdzielonej kropkami.

Utwórz ścieżkę pola w ten sposób:

topLevelField[.secondLevelField][.thirdLevelField][...]
  • Maska pola trasy obliczeniowej
    • REST: określa pola obiektu Route w odpowiedzi do zwrócenia, poprzedzone znakiem routes., np. routes.distanceMeters.
    • gRPC: określa pola obiektu Route w odpowiedzi do zwrócenia.
  • Maski pól macierzy tras obliczeniowych

Więcej informacji o tworzeniu masek pól znajdziesz w field_mask.proto.

Określanie, jakich masek pól używać

Aby określić, których masek pól chcesz używać:

  1. Żądaj wszystkich pól, używając maski pola *.
  2. Przyjrzyj się hierarchii pól w odpowiedzi i ustal, jakich pól potrzebujesz.
  3. Utwórz maskę pól, korzystając z hierarchii pól.

Na przykład dla tej częściowej odpowiedzi dotyczącej trasy transportu publicznego:

 "routes": [
  {
    "legs": [
    {
      "distanceMeters": 12886,
    }
...
]}]

Jeśli chcesz zwrócić tylko pole distanceMeters, maska pola to:

routes.legs.distanceMeters

Inny przykład: aby zwrócić w odpowiedzi wszystko w polu legs, maska pola to:

routes.legs

Podaj ścieżkę pola

Ta sekcja zawiera przykłady określania ścieżki pola w masce pola odpowiedzi.

Wywołanie REST do: computeRoutes

W pierwszym przykładzie obliczasz trasę przy użyciu wywołania REST metody computeRoutes. W tym przykładzie w nagłówku określasz maski pól zwracające w odpowiedzi pola Route.distanceMeters i Route.duration. Pamiętaj, aby przed nazwą pola dodać routes. 

-H X-Goog-FieldMask: routes.distanceMeters,routes.duration

Wywołanie REST do: computeRouteMatrix

W przypadku metody REST computeRouteMatrix używanej do obliczania macierzy tras w nagłówku wskaż wartości originIndex, destinationIndex i duration dla każdej kombinacji punktu początkowego i docelowego:

-H X-Goog-FieldMask: originIndex,destinationIndex,duration

Wywołanie gRPC

W przypadku gRPC ustaw zmienną zawierającą maskę pola odpowiedzi. Następnie możesz przekazać tę zmienną do żądania.

const (
  fieldMask = "routes.distanceMeters,routes.duration,routes.polyline.encodedPolyline"
)

Uwagi dotyczące ścieżki pola

Uwzględnij tylko pola, które są wymagane w odpowiedzi. Zwrócenie tylko tych pól, których potrzebujesz:

  • Skraca czas przetwarzania, dzięki czemu wyniki są zwracane z krótszym czasem oczekiwania.
  • Gwarantuje stabilne czas oczekiwania, jeśli w przyszłości API doda więcej pól odpowiedzi, a te nowe pola będą wymagały dodatkowego czasu obliczeniowego. Jeśli wybierzesz wszystkie pola lub wszystkie pola na najwyższym poziomie, po automatycznym uwzględnieniu wszystkich nowych pól w odpowiedzi może nastąpić spadek wydajności.
  • Przynosi to mniejszy rozmiar odpowiedzi, co przekłada się na większą przepustowość sieci.
  • Nie wysyłasz żądań zbędnych danych, co pozwala uniknąć niepotrzebnego czasu przetwarzania i rozliczonych opłat.

Poproś o token trasy

Aby zażądać, aby interfejs Routes API zwracał tokeny tras dla wygenerowanych tras, postępuj zgodnie z wymaganiami dotyczącymi zwracania tokena trasy, a następnie użyj maski pola routes.route_token do zażądania tokena:

  1. Ustaw wartość travel_mode na DRIVING.
  2. Ustaw routing_preference na TRAFFIC_AWARE lub TRAFFIC_AWARE_OPTIMAL.
  3. Sprawdź, czy żaden z punktów na trasie nie jest via punktem pośrednim.
  4. Określ maskę pola tokena trasy: 
    -H X-Goog-FieldMask: routes.route_token

Zaplanowanej trasy możesz użyć w pakiecie SDK nawigacji. Więcej informacji znajdziesz w artykułach Planowanie trasy (Android) i Planowanie trasy (iOS).

Przykład tokena trasy

Oto przykład treści żądania dotyczącego pojedynczego punktu początkowego, trasy z jednym celem podróży oraz użycia masek pól do żądania tokena trasy, wraz z czasem trwania trasy, odległością i linią łamaną trasy:

terminal
curl -X POST -d
{"origin":{
    "location": {
        "latLng":{
            "latitude":  -37.8167,
            "longitude": 144.9619
        }
    }
},
"destination":{
    "location": {
        "latLng":{
            "latitude":-37.8155,
            "longitude": 144.9663
        }
    }
},
"routingPreference":"TRAFFIC_AWARE",
"travelMode":"DRIVE"
}
-H X-Goog-FieldMask: routes.route_token,routes.duration,routes.distanceMeters,routes.polyline.encodedPolyline
'https://routes.googleapis.com/directions/v2:computeRoutes'

Więcej informacji znajdziesz w dokumentacji interfejsu Compute Routes API.