Wybierz informacje, które mają być zwracane
Gdy wywołujesz metodę obliczania trasy lub macierzy tras, musisz określić, jakie informacje chcesz uzyskać, podając pola do zwrócenia 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
.
Użycie maski pola to sprawdzona metoda projektowania, dzięki której nie żądasz zbędnych danych, co z kolei pomaga uniknąć zbędnego 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 i podaj ścieżkę pola w następujący sposób:
- Znajdź pola zawierające potrzebne informacje z interfejsu Routes API. Szczegółowe informacje znajdziesz w dokumentacji pól.
- Określ ścieżki do potrzebnych pól i utwórz dla nich maski pól: więcej informacji znajdziesz w artykule Określanie, której maski pola chcesz użyć.
Połącz maski pól dla wszystkich potrzebnych pól, rozdzielając je przecinkami. Aby np. zażądać parametru
distanceMeters
dla danego etapu trasy oraz czasu trwania każdego etapu trasy, wpisz je, oddzielając je przecinkami, bez spacji:routes.legs.distanceMeters,routes.legs.steps.duration
Wyślij maskę pola za pomocą żądania do interfejsu API. Na przykład w żądaniu cURL trzeba określić maskę pola za pomocą właściwości
-H
iX-Goog-FieldMask
:-H X-Goog-FieldMask: routes.legs.distanceMeters,routes.legs.steps.duration
Odwołania do pól
Aby zobaczyć pola, o które możesz poprosić w odpowiedzi za pomocą masek pól, zapoznaj się z odwołaniami do interfejsu Routes API, do których linki znajdziesz na poniższej liście. Określ pola w przypadku wielbłąda, tak jak w opisie. Na przykład: routePreference
.
Odwołania obejmują dostępne pola, ale aby określić pełną ścieżkę maski pola, musisz się zapoznać z hierarchią pól. Szczegółowe informacje o uzyskiwaniu hierarchii pól znajdziesz w sekcji Określanie, której maski pola chcesz użyć.
- Maska pola trasy obliczeniowej
- Obliczanie masek pól macierzy tras
- REST: określa pola treści odpowiedzi do zwrócenia.
- gRPC: określa pola obiektu RouteMatrixElement w odpowiedzi, która ma zostać zwrócona.
Określenie, których masek pól należy użyć
Oto jak możesz określić, których pól chcesz użyć, i utworzyć dla nich maski pól:
- Poproś o wszystkie pola przy użyciu maski pola
*
. - Sprawdź hierarchię pól w odpowiedzi dla wybranych pól.
Zbuduj maski pól, korzystając z hierarchii pól pokazanych w poprzednim kroku i w tym formacie:
topLevelField[.secondLevelField][.thirdLevelField][...]
Na przykład w przypadku tej częściowej odpowiedzi z trasy:
"routes": [ { "legs": [ { "steps": [ {"distanceMeters": 119}, {"distanceMeters": 41} ] } ], "distanceMeters": 160 } ]
Jeśli chcesz zwrócić tylko pole distanceMeters
dla etapu trasy, czyli ostatniego elementu distanceMeters
w poprzednim przykładzie, maska pola wygląda tak:
routes.legs.distanceMeters
Jeśli zamiast tego chcesz zwracać pole distanceMeters
dla każdego kroku etapu trasy – czyli distanceMeters
w podanym w poprzednim przykładzie steps
, maska pola wygląda tak:
routes.legs.steps.distanceMeters
Jeśli chcesz zwrócić oba wyniki, zgodnie z powyższym wynikiem maska pola wygląda tak:
routes.legs.distanceMeters,routes.legs.steps.distanceMeters
Przykładowe ścieżki maski pól
Ta sekcja zawiera więcej przykładów pokazujących, jak określić ścieżkę pola jako część maski pola odpowiedzi w wywołaniach REST i gRPC.
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 distanceMeters
i duration
trasy. Pamiętaj, by poprzedzić nazwę pola znakiem routes
.
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:
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 tylko te pola, które musisz uwzględnić w odpowiedzi, aby zwracać 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 wybierzesz wszystkie pola lub wybierzesz wszystkie pola na najwyższym poziomie, po dodaniu nowych pól, które zostaną automatycznie uwzględnione w odpowiedzi, wydajność może się zmniejszyć.
- 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.
Więcej informacji o tworzeniu maski pola znajdziesz w pliku field_mask.proto.
Poproś o token trasy
Aby zażądać, aby interfejs Routes API zwracał tokeny tras dla wygenerowanych tras, wykonaj te czynności:
- Ustaw te parametry wymagane do zwrócenia tokena trasy:
- Ustaw
travelMode
naDRIVE
. - Ustaw
routingPreference
naTRAFFIC_AWARE
lubTRAFFIC_AWARE_OPTIMAL
.
- Ustaw
- Sprawdź, czy żaden z punktów na trasie nie jest punktem na trasie
via
. - Określ maskę pola
routes.routeToken
, aby zwrócić token trasy:X-Goog-FieldMask: routes.routeToken
Tokenu trasy dla zaplanowanej trasy możesz użyć w pakiecie SDK Navigation. 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.routeToken,routes.duration,routes.distanceMeters,routes.polyline.encodedPolyline 'https://routes.googleapis.com/directions/v2:computeRoutes'
Więcej informacji znajdziesz w dokumentacji interfejsu Compute Routes API.