Wybierz informacje, które mają być zwracane

Gdy wywołujesz metodę, która oblicza trasę lub oblicza macierz tras, musisz określić wymagane informacje, określając pola, które mają być zwracane w odpowiedzi. Nie ma domyślnej listy zwróconych pól. Jeśli pominiesz tę listę, metody zwrócą błąd.

Listę pól określasz przez utworzenie maski pola odpowiedzi. Następnie przekazujesz maskę pola odpowiedzi do dowolnej metody, używając parametru $fields lub fields albo nagłówka HTTP lub gRPC X-Goog-FieldMask.

Maskowanie pól to sprawdzona metoda projektowania, dzięki której nie żądasz zbędnych danych. Pozwala to uniknąć niepotrzebnego czasu przetwarzania i rozliczonych opłat.

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

Zdefiniuj maskę pola odpowiedzi

Maska pola odpowiedzi to rozdzielana przecinkami lista ścieżek, z których każda ścieżka wskazuje unikalne pole w wiadomości odpowiedzi. Ścieżka zaczyna się od wiadomości z odpowiedzią najwyższego poziomu i używa oddzielonej kropkami ścieżki prowadzącej do określonego pola.

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

topLevelField[.secondLevelField][.thirdLevelField][...]
  • Maska pola trasy obliczeniowej
    • REST: określa pola obiektu Route w odpowiedzi, które mają zostać zwrócone, poprzedzone prefiksem routes., na przykład routes.distanceMeters.
    • gRPC: określa pola obiektu Route w odpowiedzi, która ma zostać zwrócona.
  • Obliczanie masek pól macierzy tras

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

Określenie, których masek pól należy użyć

Oto jak możesz określić, których masek pól chcesz użyć:

  1. Żądaj wszystkich pól, używając maski pola *.
  2. Przeanalizuj hierarchię pól w odpowiedzi i określ, których z nich potrzebujesz.
  3. Utwórz maskę pola, korzystając z hierarchii pól.

Na przykład dla tej częściowej odpowiedzi z trasy transportu publicznego:

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

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

routes.legs.distanceMeters

Inny przykład: aby zwrócić wszystko, co znajduje się w odpowiedzi legs, maska pola wygląda tak:

routes.legs

Określ ścieżkę pola

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

Wywołanie REST do: computeRoutes

W pierwszym przykładzie do obliczenia trasy używasz wywołania REST do metody computeRoutes. W tym przykładzie określasz w nagłówku maski pól, które zwracają w odpowiedzi pola Route.distanceMeters i Route.duration. Pamiętaj, by poprzedzić nazwę pola znakiem 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 ustaw zwracanie 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żek pól

Uwzględnij w odpowiedzi tylko te pola, które potrzebujesz. Wyświetlając tylko te pola, których potrzebujesz:

  • Skraca czas przetwarzania, dzięki czemu wyniki są zwracane z mniejszym opóźnieniem.
  • Zapewnia stabilne działanie opóźnienia, jeśli w przyszłości interfejs API będzie dodawać więcej pól odpowiedzi, a te nowe pola wymagają dodatkowego czasu na obliczenia. Jeśli wybierzesz wszystkie pola lub wybierzesz wszystkie pola na najwyższym poziomie, możesz zauważyć spadek wydajności, gdy wszystkie nowe pola będą automatycznie uwzględniane w odpowiedzi.
  • Mniejszy rozmiar odpowiedzi przekłada się na większą przepustowość sieci.
  • Zapewnia to, że nie żądasz 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 trasy dla wygenerowanych tras, postępuj zgodnie z wymaganiami dotyczącymi zwracania tokena trasy, a następnie użyj maski pola routes.route_token do wysłania żądania o token:

  1. Ustaw 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 punktem na trasie via.
  4. Określ maskę pola tokena trasy: 
    -H X-Goog-FieldMask: routes.route_token

Możesz użyć zaplanowanej trasy w pakiecie Navigation SDK. 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 dla pojedynczej trasy z jednym miejscem docelowym, 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.