Wybierz informacje, które mają być zwracane

Gdy wywołujesz metodę wyznaczania trasy lub macierzy tras, musisz określić wymagane informacje, wymieniając pola, 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 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.

Dobrą metodą projektowania jest użycie maski pola, dzięki której zbędnych danych, co z kolei pozwala uniknąć niepotrzebnego czasu przetwarzania i rozliczonych opłat.

Więcej informacji o parametrach adresu URL: Parametry systemowe.

Zdefiniuj maskę pola odpowiedzi

Maska pola odpowiedzi to rozdzielana przecinkami lista ścieżek, gdzie każda Path określa unikalne 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.

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 na przykład poprosić o wartość distanceMeters dla danego etapu trasy oraz czas 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.

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

• Maska pola trasy obliczeniowej
  • 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 wartości obiektu Route w kolumnie odpowiedź na żądanie.
• Obliczanie masek pól macierzy tras
  • REST: określa pola wartości Treść odpowiedzi zwrócić.
  • gRPC: określa pola wartości RouteMatrixElement .

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. 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][...]

   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 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 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 użyjesz wywołania REST do funkcji Metoda computeRoutes do obliczenia trasę. 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 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 na temat ścieżek pól

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

• Skraca czas przetwarzania, dzięki czemu wyniki są zwracane z mniejszym opóźnieniem.
• Zapewnia stabilne działanie opóźnienia. 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.

Uwaga: podczas przeanalizowania wiadomości z odpowiedzią i pola w polu odpowiedź zawiera wartość domyślną, to pole może zostać pominięte w odpowiedzi, nawet jeśli została określona w masce pola odpowiedzi. Więcej informacji: Przewodnik po języku (proto3). Na przykład przy obliczaniu macierzy tras Pole distanceMeters odpowiedzi może zawierać wartość 0, wartość domyślną. Ponieważ 0 to wartość domyślna parametru distanceMeters, jest pomijany w odpowiedzi.

Więcej informacji o tworzeniu maski pola znajdziesz w dokumentacji 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 zwracać 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 wygenerowania tokena.

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

Przykład tokena 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: Dokumentacja interfejsu Compute Routes API.