Deweloperzy z Europejskiego Obszaru Gospodarczego (EOG)

Wybierz pola, które mają być zwracane

Gdy wysyłasz żądanie trasy lub macierzy tras, musisz użyć maski pola, aby określić, jakie informacje powinna zwracać odpowiedź. Nie ma domyślnej listy zwracanych pól. Jeśli nie określisz maski pola, metody zwrócą błąd.

Użycie maski pola gwarantuje też, że nie będziesz prosić o niepotrzebne dane, co z kolei pomaga zmniejszyć opóźnienie odpowiedzi i uniknąć zwracania informacji, których Twój system nie potrzebuje.

Listę potrzebnych pól możesz określić w masce pola odpowiedzi. Następnie przekazujesz maskę pola odpowiedzi do jednej z metod, używając parametru adresu URL $fields lub fields albo nagłówka HTTP lub gRPC X-Goog-FieldMask.

Więcej informacji o parametrach adresu URL znajdziesz w artykule o parametrach systemowych.

Definiowanie maski pola odpowiedzi

Maska pola odpowiedzi to lista rozdzielona przecinkami ścieżek, z których każda określa unikalne pole w komunikacie odpowiedzi. Ścieżka zaczyna się od komunikatu odpowiedzi najwyższego poziomu i używa ścieżki rozdzielanej kropkami do określonego pola.

Utwórz i określ ścieżkę pola w ten sposób:

  1. Znajdź pola zawierające potrzebne informacje. Więcej informacji znajdziesz w sekcji Odniesienia do pól.
  2. Określ ścieżki do pól, których potrzebujesz, 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, oddzielając je przecinkami. Jeśli na przykład chcesz poprosić o distanceMeters dla etapu trasy oraz czas trwania każdego kroku etapu trasy, wpisz obie te wartości, rozdzielając je przecinkiem, bez spacji:

    routes.legs.distanceMeters,routes.legs.steps.duration

  4. Wyślij maskę pola z żądaniem do interfejsu API. Na przykład w żądaniu curl maskę pola określa się za pomocą -H i X-Goog-FieldMask:

    -H X-Goog-FieldMask: routes.legs.distanceMeters,routes.legs.steps.duration
Przykłady i dodatkowe informacje znajdziesz w sekcjach poniżej.

Odniesienia do pól

Aby zobaczyć pola, o które możesz poprosić w odpowiedzi za pomocą masek pól, zapoznaj się z dokumentacją interfejsu Routes API Compute Routes lub Compute Route Matrix, do której linki znajdziesz na liście poniżej. Pola należy podawać w formacie camelCase, jak pokazano w dokumentacji. Na przykład: routePreference.

Te materiały referencyjne zawierają dostępne pola, ale aby określić pełną ścieżkę maski pola, musisz odwołać się do hierarchii pól. Szczegółowe informacje o uzyskiwaniu hierarchii pól znajdziesz w sekcji Określanie maski pola, której chcesz użyć.

  • Maska pola obliczania trasy
    • REST: określa pola obiektu Route w odpowiedzi, które mają zostać zwrócone, z prefiksem routes., np. routes.distanceMeters.
    • gRPC: określa pola obiektu Route w odpowiedzi, które mają zostać zwrócone.
  • Maski pól macierzy tras

Określanie masek pól do użycia

Oto jak możesz określić, których pól chcesz używać, i utworzyć dla nich maski:

  1. Poproś o wszystkie pola, używając maski pola *.
  2. Sprawdź hierarchię pól w odpowiedzi, aby znaleźć odpowiednie pola.

  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 zwrócić pole distanceMeters dla każdego kroku etapu trasy, czyli distanceMeters w sekcji steps w poprzednim przykładzie, maska pola będzie wyglądać tak:

routes.legs.steps.distanceMeters

Jeśli chcesz zwrócić oba te pola, maska pola będzie wyglądać tak:

routes.legs.distanceMeters,routes.legs.steps.distanceMeters

Przykładowe ścieżki masek pól

Ta sekcja zawiera więcej przykładów określania ścieżki pola jako części maski pola odpowiedzi w wywołaniach REST i gRPC.

Wywołanie REST do computeRoutes

W pierwszym przykładzie użyjesz wywołania REST metody computeRoutes, aby obliczyć trasę. W tym przykładzie w nagłówku określasz maski pól, aby w odpowiedzi zwrócić pola trasy distanceMeters i duration. Pamiętaj, aby przed nazwą pola dodać 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, że dla każdej kombinacji miejsca początkowego i docelowego mają być zwracane parametry originIndex, destinationIndex i duration:

X-Goog-FieldMask: originIndex,destinationIndex,duration

Wywołanie gRPC do computeRoutes

W przypadku metody gRPC computeRoutes używanej do obliczania trasy ustaw zmienną zawierającą maskę pola odpowiedzi, aby zwracać w odpowiedzi pola trasy distanceMeters, duration i zakodowanej linii łamanej. Następnie możesz przekazać tę zmienną do żądania:

const (
  fieldMask = "routes.distanceMeters,routes.duration,routes.polyline.encodedPolyline"
)

Wywołanie gRPC do computeRouteMatrix

W przypadku metody gRPC computeRouteMatrix używanej do obliczania macierzy tras ustaw zmienną zawierającą maskę pola odpowiedzi, aby określić, że dla każdej kombinacji miejsca rozpoczęcia i zakończenia podróży mają być zwracane wartości originIndex, destinationIndex i duration. Następnie możesz przekazać tę zmienną do żądania:

const (
  fieldMask = "originIndex,destinationIndex,duration"
)

Uwagi dotyczące ścieżki pola

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

  • skraca czas przetwarzania, dzięki czemu wyniki są zwracane z mniejszym opóźnieniem;
  • Zapewnia stabilne opóźnienie. Jeśli wybierzesz wszystkie pola lub wszystkie pola na najwyższym poziomie, może dojść do spadku wydajności, gdy zostaną dodane nowe pola, które zostaną automatycznie uwzględnione w odpowiedzi.
  • Zmniejsza rozmiar odpowiedzi, co przekłada się na większą przepustowość sieci.
  • Nie prosisz o niepotrzebne dane, co pozwala uniknąć niepotrzebnego czasu przetwarzania i opłat.

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