Wybieranie informacji do zwrócenia

Gdy wywołujesz metodę obliczania trasy lub macierzy tras, musisz określić, jakie informacje chcesz otrzymać, podając pola, które mają zostać zwrócone w odpowiedzi. Nie ma domyślnej listy zwracanych pól. Jeśli pominiesz tę listę, metody zwrócą błąd.

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

Używanie maski pola to dobra praktyka projektowania, która pozwala uniknąć przesyłania niepotrzebnych danych, a to z kolei pozwala uniknąć niepotrzebnego czasu przetwarzania i opłat.

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

Definiowanie maski pola odpowiedzi

Maska pola odpowiedzi to lista ścieżek oddzielonych przecinkami, gdzie każda ścieżka określa niepowtarzalne pole w wiadomości odpowiedzi. Ścieżka zaczyna się od wiadomości odpowiedzi na najwyższym poziomie i korzysta ze ścieżki oddzielonej kropkami do określonego pola.

Aby utworzyć i określić ścieżkę pola, wykonaj te czynności:

1. Znajdź pola zawierające potrzebne informacje w interfejsie Routes API. Więcej informacji znajdziesz w opisie odwołań do pól.
2. Określ ścieżki do potrzebnych pól i utwórz dla nich maski pól: szczegółowe informacje znajdziesz w sekcji Określanie maski pola, której chcesz użyć.

3. Połącz maski pól dla wszystkich potrzebnych pól, rozdzielając je przecinkami. Aby na przykład poprosić o distanceMeters dla danego odcinka trasy oraz o czas trwania każdego kroku na tym odcinku, wpisz oba te elementy rozdzielone przecinkami bez spacji:

   routes.legs.distanceMeters,routes.legs.steps.duration

4. Wyślij maskę pola z żądaniem interfejsu API. Na przykład w żądaniu cURL musisz podać maskę pola z wartościami -H i X-Goog-FieldMask:

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

Przykłady i szczegółowe informacje znajdziesz w następnych sekcjach.

Odwołania do pól

Aby sprawdzić, których pól możesz zażądać w odpowiedzi za pomocą masek pól, zapoznaj się z dokumentacją interfejsu Routes API, do której linki znajdziesz na liście poniżej. Wskazuje pola w stylu „camel case” (wielkie litery w słowie od pierwszej litery) zgodnie z opisem. Na przykład: routePreference.

Natomiast wartości parametrów musisz wpisywać w taki sposób. Na przykład w przypadku routingPreference musisz wpisać TRAFFIC_AWARE.

Te odwołania obejmują dostępne pola, ale aby określić pełną ścieżkę maski pola, musisz zapoznać się z hierarchią pól. Szczegółowe informacje o hierarchii pól znajdziesz w artykule Określanie maski pola, której chcesz użyć.

• Oblicz maskę pola trasy
  • REST: określa pola obiektu Route w odpowiedzi, które mają zostać zwrócone, z prefiksem routes., na przykład routes.distanceMeters.
  • gRPC: określa pola obiektu Route w odpowiedzi, które mają zostać zwrócone.
• Oblicz maski pól macierzy tras
  • REST: określa pola elementu Response body, które mają być zwracane.
  • gRPC: określa pola obiektu RouteMatrixElement w odpowiedzi, które mają zostać zwrócone.

Określanie masek pól

Aby określić, których pól chcesz użyć, i utworzyć dla nich maski pól:

1. Żądaj wszystkich pól, używając maski pola *.
   Ostrzeżenie: możesz używać tej maski pola z symbolem wieloznacznym podczas tworzenia aplikacji, aby określić, których pól potrzebujesz, ale nie używaj jej w wersji produkcyjnej. Wysyłanie żądań do wszystkich pól w produkcji wiąże się z wyższymi kosztami i dłuższym czasem odpowiedzi. Koszty mogą też nieoczekiwanie wzrosnąć, gdy dodamy bardziej zaawansowane funkcje, ponieważ ta maska pola będzie je automatycznie uwzględniać. Zamiast tego poproś tylko o pola, których potrzebujesz, aby zminimalizować koszty i czas oczekiwania na odpowiedź.
2. Sprawdź hierarchię pól w odpowiedziach dotyczących wybranych pól.

3. Utwórz maski pól, korzystając z hierarchii pól pokazanej w poprzednim kroku, w tym formacie:

   topLevelField[.secondLevelField][.thirdLevelField][...]

   Uwaga: na liście ścieżek pól nie używaj spacji.

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 ostatnie pole distanceMeters w poprzednim przykładzie, maska pola będzie wyglądać tak:

routes.legs.distanceMeters

Jeśli chcesz zamiast tego zwrócić pole distanceMeters dla każdego kroku na trasie, czyli pole distanceMeters w elementzie steps w poprzednim przykładzie, maska pola będzie wyglądać tak:

routes.legs.steps.distanceMeters

Jeśli chcesz zwrócić oba pola, z wynikiem powyżej, maska pola będzie wyglądać tak:

routes.legs.distanceMeters,routes.legs.steps.distanceMeters

Przykładowe ścieżki maski pola

W tej sekcji znajdziesz więcej przykładów określania ścieżki pola w ramach 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 w nagłówku podajesz maski pól, aby zwrócić w odpowiedzi pola distanceMeters i duration. Pamiętaj, aby przed nazwą pola umieścić prefiks routes.

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

Wywołanie REST do computeRouteMatrix

W przypadku metody REST computeRouteMatrix, która służy do obliczania macierzy tras, w nagłówku określ, że chcesz zwrócić parametry 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 dotyczące ścieżki pola

Aby zwrócić tylko potrzebne pola, uwzględnij w odpowiedzi tylko te pola:

• Krótszy czas przetwarzania, dzięki czemu wyniki są zwracane z mniejszym opóźnieniem.
• Zapewnia stabilną wydajność z niskim opóźnieniem. Jeśli wybierzesz wszystkie pola lub wszystkie pola na najwyższym poziomie, możesz zauważyć spadek wydajności po dodaniu nowych pól i ich automatycznym uwzględnieniu w odpowiedzi.
• Powoduje mniejszy rozmiar odpowiedzi, co przekłada się na większą przepustowość sieci.
• Upewnij się, że nie prosisz o niepotrzebne dane, co pomoże Ci uniknąć niepotrzebnego czasu przetwarzania i naliczonych opłat.

Uwaga: gdy podczas analizowania odpowiedzi pole w niej zawarte zawiera swoją wartość domyślną, może ono zostać pominięte w odpowiedzi, nawet jeśli zostało określone w masce pola odpowiedzi. Więcej informacji znajdziesz w przewodniku po językach (proto3). Podczas obliczania macierzy tras pole distanceMeters w odpowiedzi może zawierać wartość 0, czyli wartość domyślną. Wartość domyślna parametru distanceMeters to 0, dlatego nie jest ona uwzględniana w odpowiedzi.

Więcej informacji o tworzeniu maski pola znajdziesz w pliku field_mask.proto.

Prośba o token trasy

Aby poprosić interfejs Routes API o zwrócenie tokenów trasy dla wygenerowanych tras, wykonaj te czynności:

1. Ustaw te parametry wymagane do zwrócenia tokenu trasy:
   • Ustaw travelMode na DRIVE.
   • Ustaw wartość routingPreference na TRAFFIC_AWARE lub TRAFFIC_AWARE_OPTIMAL.
2. Sprawdź, czy żaden z punktów na trasie nie jest punktem via.
3. Aby zwrócić token trasy, określ maskę pola routes.routeToken:

   X-Goog-FieldMask: routes.routeToken

Uwaga: ze względu na dynamiczne warunki drogowe trasy wygenerowane za pomocą danego tokena mogą różnić się od zaplanowanej trasy. Aby zminimalizować różnice, użyj tokena w ciągu kilku minut od jego wygenerowania.

Możesz użyć tokenu trasy dla zaplanowanej trasy w pakiecie SDK do nawigacji. Więcej informacji znajdziesz w artykule Planowanie trasy (Android) lub Planowanie trasy (iOS).

Przykład tokenu trasy

Oto przykładowy tekst żądania cURL dla trasy z jednym punktem początkowym i jednym punktem docelowym, w którym maski pól służą do żądania tokenu trasy wraz z czasem trwania, odległością i polilinią 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.