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 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 adresu URL znajdziesz w sekcji 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 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 z interfejsu 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 wraz z żądaniem 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 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 znajdują się na poniższej liście. Wskazuje pola w wielkim natężeniu, jak pokazano w dokumentacji. 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 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, poprzedzone 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

Wybieranie masek pól

Oto jak możesz 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 *.
  2. Sprawdź hierarchię pól w odpowiedzi dla 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][...]

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 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 pola

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, 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 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 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 stabilne działanie opóźnienia. 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.
  • 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.

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 tokena 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

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 tokena trasy

Oto przykład treści żądania cURL dla pojedynczej trasy z pojedynczym 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.