Wybierz pola do zwrócenia
Gdy wysyłasz żądanie dotyczące trasy lub macierzy tras, musisz użyć maski pola, aby określić, jakie informacje powinna zwrócić 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 system nie potrzebuje.
Listę potrzebnych pól określasz w masce pola odpowiedzi. Następnie przekazujesz maskę pola odpowiedzi do jednej z tych metod, 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, z których każda określa unikalne pole w wiadomości z odpowiedzią. Ścieżka zaczyna się od wiadomości odpowiedzi najwyższego poziomu i używa ścieżki rozdzielonej kropkami do określonego pola.
Skonstruuj i określ ścieżkę pola w ten sposób:
- Znajdź pola zawierające potrzebne informacje. Więcej informacji znajdziesz w opisie odwołań do pól.
- Określ ścieżki do potrzebnych pól i utwórz dla nich maski pól: więcej informacji znajdziesz w artykule Określanie maski pola, której chcesz użyć.
Połącz maski pól wszystkich potrzebnych pól, oddzielając je przecinkami. Jeśli na przykład chcesz poprosić o
distanceMetersdla odcinka trasy oraz czas trwania każdego kroku odcinka trasy, wpisz je oba, rozdzielając je przecinkiem bez spacji:routes.legs.distanceMeters,routes.legs.steps.duration
Wyślij maskę pola wraz z żądaniem do interfejsu API. Na przykład w żądaniu curl maskę pola określa się za pomocą znaków
-HiX-Goog-FieldMask:-H X-Goog-FieldMask: routes.legs.distanceMeters,routes.legs.steps.duration
Odwołania 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 poniższej liście. Pola należy podawać w notacji camel case, jak pokazano w dokumentacji. 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. Szczegółowe informacje o uzyskiwaniu hierarchii pól znajdziesz w artykule Określanie, której maski pola chcesz użyć.
- Maska pola trasy obliczeniowej
- Maski pól Compute Route Matrix
- REST: określa pola treści odpowiedzi, które mają być zwracane.
- 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ć, których pól chcesz używać, i utworzyć dla nich maski pól:
- Poproś o wszystkie pola, używając maski pola
*. - Sprawdź hierarchię pól w odpowiedzi, aby znaleźć potrzebne pola.
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 odpowiedzi częściowej z trasy:
"routes": [ { "legs": [ { "steps": [ {"distanceMeters": 119}, {"distanceMeters": 41} ] } ], "distanceMeters": 160 } ]
Jeśli chcesz zwrócić tylko pole distanceMeters dla odcinka trasy, czyli ostatnie pole 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 odcinka trasy, czyli pole 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 wyniki, 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 do 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 trasy distanceMeters i duration. Pamiętaj, aby przed nazwą pola dodać znak 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 punktu początkowego i docelowego mają być zwracane wartości 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 zakodowaną linię łamaną. 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 wartości 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:
- Skraca czas przetwarzania, dzięki czemu wyniki są zwracane z mniejszym opóźnieniem.
- Zapewnia stabilną wydajność w zakresie opóźnień. Jeśli wybierzesz wszystkie pola lub wszystkie pola na najwyższym poziomie, po dodaniu nowych pól i automatycznym uwzględnieniu ich w odpowiedzi może nastąpić spadek wydajności.
- Zmniejsza rozmiar odpowiedzi, co przekłada się na większą przepustowość sieci.
- Gwarantuje, że nie będziesz prosić o niepotrzebne dane, co pomaga uniknąć niepotrzebnego czasu przetwarzania i naliczonych opłat.
Więcej informacji o tworzeniu maski pola znajdziesz w pliku field_mask.proto.