Wybieranie pól do zwrócenia
Gdy wysyłasz prośbę o trasę lub macierz tras, musisz użyć maski pola, aby określić, jakie informacje powinna zawierać 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 zapewnia 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 określasz w masce pola odpowiedzi. Następnie przekazujesz
maskę pola odpowiedzi do dowolnej metody, używając parametru adresu URL $fields lub
fields, albo nagłówka HTTP lub gRPC X-Goog-FieldMask.
Więcej informacji o parametrach adresów URL znajdziesz w sekcji Parametry systemowe.
Definiowanie maski pola odpowiedzi
Maska pola odpowiedzi to lista ścieżek oddzielonych przecinkami, gdzie każda ścieżka określa unikalne pole w wiadomości odpowiedzi. Ścieżka zaczyna się od wiadomości odpowiedzi najwyższego poziomu i używa ścieżki oddzielonej kropkami do określonego pola.
Ścieżkę pola skonstruuj i określ w ten sposób:
- Znajdź pola zawierające potrzebne informacje. Więcej informacji znajdziesz w sekcji Odniesienia do pól.
- Określ ścieżki do potrzebnych pól i skonstruuj dla nich maski pól: więcej informacji znajdziesz w sekcji Określanie maski pola, której chcesz użyć.
Połącz maski pól dla wszystkich potrzebnych pól, oddzielając je przecinkami. Aby na przykład poprosić o
distanceMetersdla etapu trasy oraz czas trwania każdego kroku etapu trasy, wpisz je oba, oddzielając je przecinkiem i bez spacji:routes.legs.distanceMeters,routes.legs.steps.duration
Wyślij maskę pola z żądaniem do interfejsu API. Na przykład w żądaniu curl maskę pola określisz za pomocą
-HiX-Goog-FieldMask:-H X-Goog-FieldMask: routes.legs.distanceMeters,routes.legs.steps.duration
Odniesienia do pól
Aby zobaczyć pola, o które możesz poprosić w odpowiedzi za pomocą masek pól, zapoznaj się z odniesieniami do interfejsu Routes API Compute Routes lub Compute Route Matrix, które znajdziesz na tej liście. Pola określaj w notacji camelCase, jak pokazano w pliku referencyjnym. Na przykład routePreference.
Te odniesienia zawierają dostępne pola, ale aby określić pełną ścieżkę maski pola, musisz zapoznać się z hierarchią pól. Więcej informacji o uzyskiwaniu hierarchii pól znajdziesz w sekcji Określanie maski pola, której chcesz użyć.
- Maska pola obliczania trasy
- Maski pól obliczania macierzy tras
- REST: określa pola treści odpowiedzi, które mają zostać zwrócone.
- gRPC: określa pola obiektu RouteMatrixElement w odpowiedzi, które mają zostać zwrócone.
Określanie masek pól do użycia
Oto jak możesz określić pola, których chcesz użyć, i skonstruować dla nich maski pól:
- Poproś o wszystkie pola , używając maski pola
*. - Sprawdź hierarchię pól w odpowiedzi na pola, których potrzebujesz.
Skonstruuj maski pól , używając 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 distanceMeters w poprzednim przykładzie, maska pola będzie wyglądać tak:
routes.legs.distanceMeters
Jeśli zamiast tego 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
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 używasz wywołania REST do metody
computeRoutes, aby obliczyć
trasę. W tym przykładzie w nagłówku określasz maski pól, aby w odpowiedzi zwrócić pola distanceMeters i duration trasy. Pamiętaj, aby dodać przedrostek routes przed nazwą pola.
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 dla każdej kombinacji punktu początkowego
i docelowego zwracać
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 w odpowiedzi zwracać pola distanceMeters, duration i zakodowaną linię łamaną trasy. 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ć zwracanie originIndex, destinationIndex i duration dla każdej kombinacji punktu początkowego i docelowego. Następnie możesz przekazać tę zmienną do żądania:
const ( fieldMask = "originIndex,destinationIndex,duration" )
Uwagi dotyczące ścieżki pola
W odpowiedzi uwzględnij tylko te pola, które są Ci potrzebne, aby zwracać tylko te pola, których potrzebujesz:
- Skraca czas przetwarzania, dzięki czemu wyniki są zwracane z mniejszym opóźnieniem.
- Zapewnia stabilną wydajność opóźnienia. Jeśli wybierzesz wszystkie pola lub wszystkie pola na najwyższym poziomie, możesz zauważyć spadek wydajności, gdy dodamy nowe pola, które będą automatycznie uwzględniane w odpowiedzi.
- Zmniejsza rozmiar odpowiedzi, co przekłada się na większą przepustowość sieci.
- Zapewnia, że nie będziesz prosić o niepotrzebne dane, co pomaga uniknąć niepotrzebnego czasu przetwarzania i naliczania opłat.
Więcej informacji o tworzeniu maski pola znajdziesz w pliku field_mask.proto.