Wybieranie pól zwracanych

Gdy wysyłasz żądanie trasy lub macierzy tras, musisz użyć maski pola, aby określić, jakie informacje mają zostać zwrócone w odpowiedzi. Nie ma domyślnej listy zwracanych pól. Jeśli nie określisz maski pola, metody zwracają błąd.

Użycie maski pola zapewnia też, że nie wysyłasz niepotrzebnych danych, co z kolei pomaga w zmniejszeniu opóźnienia odpowiedzi i uniknięciu zwracania informacji, których Twój system nie potrzebuje.

Listę potrzebnych pól określasz w polu maski 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.

Więcej informacji o parametrach adresów URL znajdziesz w artykule Parametry systemowe.

Definiowanie maski 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 podać ścieżkę pola, wykonaj te czynności:

  1. Znajdź pola zawierające potrzebne informacje. 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 określić maskę pola za pomocą -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, których możesz zażądać w odpowiedzi za pomocą masek pól, zapoznaj się z dokumentacją interfejsu Routes API dotyczącą obliczania tras lub obliczania macierzy tras, 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.

Te odwołania obejmują dostępne pola, ale aby określić pełną ścieżkę maski pola, musisz zapoznać się z hierarchią pól. Więcej informacji 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, z 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

Aby 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 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 elementach 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, która służy do obliczania macierzy tras, w nagłówku określ, że chcesz zwrócić wartoś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 stabilną wydajność z niskim opóźnieniem. Jeśli wybierzesz wszystkie pola lub wszystkie pola na najwyższym poziomie, możesz zauważyć spadek wydajności, gdy dodasz nowe pola i automatycznie uwzględnisz je w odpowiedzi.
  • Powoduje mniejszy rozmiar odpowiedzi, co przekłada się na większą przepustowość sieci.
  • Upewnia się, że nie prosisz o niepotrzebne dane, co pomaga uniknąć zbędnego czasu przetwarzania i niepotrzebnych opłat.

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