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:

1. Znajdź pola zawierające potrzebne informacje z interfejsu Routes API. Szczegółowe informacje znajdziesz w dokumentacji pól.
2. 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ć.

3. 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

4. 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 i X-Goog-FieldMask:

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

Przykłady i więcej informacji znajdziesz w kolejnych sekcjach.

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.

Dlatego musisz wpisać wartości parametrów, jak pokazano na obrazku. Na przykład w przypadku routingPreference musisz wpisać TRAFFIC_AWARE.

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
  • 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
  • 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:

1. Poproś o wszystkie pola przy użyciu maski pola *.
   Uwaga: tej maski pola z symbolem wieloznacznym możesz używać w trakcie opracowywania do określenia potrzebnych pól, ale nie używaj jej w środowisku produkcyjnym. Żądanie wszystkich pól w środowisku produkcyjnym skutkuje wyższymi kosztami i dłuższym czasem odpowiedzi. Koszty mogą też nieoczekiwanie wzrosnąć w miarę dodawania bardziej zaawansowanych funkcji, ponieważ są one automatycznie uwzględniane w tej masce pola. Zamiast tego wysyłaj prośby tylko o te pola, których potrzebujesz, aby zminimalizować koszty i czas odpowiedzi na żądanie.
2. Sprawdź hierarchię pól w odpowiedzi dla wybranych pól.

3. Zbuduj maski pól, korzystając z hierarchii pól pokazanych w poprzednim kroku i w tym formacie:

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

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

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.

Uwaga: jeśli wiadomość z odpowiedzią zostanie przeanalizowana, a pole w odpowiedzi zawiera swoją wartość domyślną, to pole może zostać pominięte w odpowiedzi, nawet jeśli zostało określone w masce pola odpowiedzi. Więcej informacji znajdziesz w Przewodniku po języku (proto3). Na przykład, gdy obliczasz macierz tras, pole distanceMeters odpowiedzi może zawierać wartość 0, która jest jej wartością domyślną. Ponieważ 0 to wartość domyślna parametru distanceMeters, jest ona pomijana w odpowiedzi.

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:

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

   X-Goog-FieldMask: routes.routeToken

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

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.