Wybierz informacje, które mają być zwracane

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 zwróconych pól. Jeśli pominiesz tę listę, metody zwrócą błąd.

Listę pól określasz, tworząc maskę pola odpowiedzi. Następnie przechodzisz maskę pola odpowiedzi w dowolnej z metod przy użyciu parametru adresu URL $fields lub fields albo przy użyciu 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.

Zdefiniuj maskę 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 rozpoczyna się od wiadomości z odpowiedzią najwyższego poziomu i wykorzystuje parametr oddzielone kropkami do określonego pola.

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

  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: 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 za pomocą żądania do interfejsu API. Na przykład w żądaniu cURL musisz określić maskę pola za pomocą parametrów -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óre pola możesz poprosić o zwrócenie 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.

Obejmują one dostępne pola. aby określić pełną ścieżkę maski pola, musisz jednak odnieść się do hierarchii pól. Szczegółowe informacje o uzyskiwaniu hierarchii pól znajdziesz w sekcji Określanie, której maski pola chcesz użyć.

  • Oblicz maskę pola trasy
    • REST: określa pola wartości obiektu Route w kolumnie odpowiedź do zwrócenia poprzedzona ciągiem 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

Wybieranie masek pól

Aby 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 *.
  2. Przejrzyj hierarchię pól w odpowiedzi na żądanie wybranych polach.

  3. 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 ostatni element distanceMeters w poprzednim przykładzie, maska pola wygląda tak:

routes.legs.distanceMeters

Jeśli chcesz zamiast tego zwracać pole distanceMeters dla każdego etapu trasy: czyli distanceMeters w steps w poprzednim przykładzie, maska pola 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 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 w nagłówku podajesz maski pól, aby zwrócić w odpowiedzi pola distanceMeters i duration. Pamiętaj, by poprzedzić nazwę pola znakiem routes.

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

Wywołanie REST do: computeRouteMatrix

W przypadku trybu REST computeRouteMatrix używana do obliczania macierzy tras, w nagłówku należy określić do zwrócenia originIndex, destinationIndex i duration dla każdej kombinacji źródła i miejsce docelowe:

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

Uwzględnij tylko te pola, które są wymagane w odpowiedzi, aby zwrócić tylko Potrzebne pola:

  • Krótszy czas przetwarzania, dzięki czemu wyniki są zwracane z mniejszym opóźnieniem.
  • Zapewnia stabilną wydajność z niskim opóźnieniem. Jeśli zaznacz wszystkie pola. Jeżeli wybierzesz wszystkie pola na najwyższym poziomie, po dodaniu nowych pól spowoduje pogorszenie wydajności. automatycznie uwzględnione 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.

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

Poproś o token trasy

Aby poprosić interfejs Routes API o zwrócenie tokenów 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 via.
  3. Aby zwrócić token trasy, określ maskę pola routes.routeToken: 
    X-Goog-FieldMask: routes.routeToken

Tokenu trasy dla zaplanowanej trasy możesz użyć w pakiecie SDK Navigation. Więcej informacji znajdziesz w artykule Planowanie trasy (Android) lub Planowanie trasy (iOS).

Przykład tokenu trasy

Oto przykład treści żądania cURL dla pojedynczego punktu początkowego, pojedynczego miejsca docelowego trasa, korzystając z masek pól do żądania tokena trasy wraz z trasą czas trwania, odległość i linia łamana 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.