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 adresu URL znajdziesz w sekcji Parametry systemowe.

Definiowanie maski 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 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 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 wielkim natężeniu, jak pokazano w dokumentacji. Na przykład: routePreference.

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 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óre mają zostać zwrócone.
  • Obliczanie masek 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. 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][...]

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 używanej do obliczania macierzy tras w nagłówku określ, aby zwrócić 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.
  • Upewnij się, że nie prosisz o niepotrzebne dane, co pomoże uniknąć niepotrzebnego czasu przetwarzania i naliczonych opłat.

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

Prośba 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 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. Określ maskę pola routes.routeToken, aby zwracać token trasy: 
    X-Goog-FieldMask: routes.routeToken

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