Wybieranie informacji zwracanych

Przy wywołaniu metody polegającej na obliczeniu trasy lub macierzy tras musisz określić, jakie informacje chcesz uzyskać, określając pola, które mają się pojawić w odpowiedzi. Nie ma domyślnej listy zwracanych pól. Jeśli pominiesz tę listę, metody zwrócą błąd.

Aby określić listę pól, utwórz maskę pola odpowiedzi. Następnie przekaż maskę pola odpowiedzi do wybranej metody za pomocą parametru adresu URL $fields lub fields albo nagłówka HTTP lub gRPC X-Goog-FieldMask.

Maskowanie pól to dobra metoda projektowa, która pozwala uniknąć żądania zbędnych danych, co pozwala uniknąć niepotrzebnego czasu przetwarzania i rozliczonych opłat.

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

Zdefiniuj maskę pola odpowiedzi

Maska pola odpowiedzi jest listą rozdzielonych przecinkami ścieżek, gdzie każda ścieżka określa unikalne pole w wiadomości z odpowiedzią. Ścieżka rozpoczyna się od wiadomości z odpowiedzią najwyższego poziomu i używa oddzielonej kropką ścieżki do określonego pola.

Utwórz ścieżkę pola w następujący 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, która ma zostać zwrócona.
  • Maski pól macierzy tras obliczeniowych

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

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

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

  1. Wyślij żądanie dotyczące wszystkich pól, używając maski pola *.
  2. Przyjrzyj się hierarchii pól w odpowiedzi i ustal, których pól potrzebujesz.
  3. Utwórz maskę pola, korzystając z hierarchii pól.

Na przykład w przypadku tej częściowej odpowiedzi z 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 z tekstu 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 do obliczenia trasy używasz wywołania REST metody computeRoutes. W tym przykładzie w nagłówku określasz maski pól, które zwracają w odpowiedzi pola Route.distanceMeters i Route.duration. Pamiętaj, aby przed nazwą pola poprzedzić 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 określ zwracanie 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 na temat ścieżki pola

Uwzględnij w odpowiedzi tylko pola, które są wymagane. Zwracając tylko te pola, które są potrzebne:

  • Skraca czas przetwarzania, dzięki czemu wyniki są zwracane z krótszym czasem oczekiwania.
  • Gwarantuje stabilne opóźnienia, jeśli interfejs API doda w przyszłości więcej pól odpowiedzi, co będzie wymagało dodatkowego czasu obliczania. Jeśli wybierzesz wszystkie pola lub wybierzesz wszystkie pola na najwyższym poziomie, może nastąpić spadek wydajności, gdy wszystkie nowe pola zostaną automatycznie uwzględnione w odpowiedzi.
  • Mniejszy rozmiar odpowiedzi przekłada się na większą przepustowość sieci.
  • Zapewnia brak żądań zbędnych danych, co pozwala uniknąć niepotrzebnego czasu przetwarzania i naliczania opłat.

Poproś o token trasy

Aby poprosić o zwracanie tokenów tras wygenerowanych przez interfejs Routes API, postępuj zgodnie z wymaganiami dotyczącymi zwracania tokena trasy, a następnie użyj maski pola routes.route_token do żądania tokena:

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

Możesz korzystać z zaplanowanej trasy 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 cURL dotyczącego trasy pojedynczego punktu początkowego i jednego miejsca docelowego z użyciem masek pól do żądania tokena trasy wraz z czasem trwania trasy, odległością i linią łamaną trasy:

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-Api-Key: YOUR_API_KEY' \
-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.