Wybierz pola do zwrócenia

Gdy wysyłasz żądanie 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 Twój system nie potrzebuje.

Listę potrzebnych pól określasz w masce pola odpowiedzi. Następnie przekazujesz maskę pola odpowiedzi do jednej z tych metod za pomocą parametru adresu URL $fields lub fields albo za pomocą nagłówka HTTP lub gRPC X-Goog-FieldMask.

Więcej informacji o parametrach adresów URL znajdziesz w sekcji Parametry systemu.

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 zawiera ścieżkę do określonego pola rozdzieloną kropkami.

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

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: więcej informacji znajdziesz w artykule Określanie maski pola, której chcesz użyć.

3. Połącz maski pól wszystkich potrzebnych pól, rozdzielając je przecinkami. Aby na przykład poprosić o distanceMeters dla odcinka trasy oraz czas trwania każdego kroku odcinka trasy, wpisz oba te parametry, rozdzielając je przecinkiem i nie dodając spacji:

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

4. Wyślij maskę pola z żądaniem interfejsu API. Na przykład w żądaniu curl maskę pola określa się za pomocą parametrów -H i X-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. Określ pola w notacji camel case, jak pokazano w dokumentacji. Na przykład: routePreference.

Te odwołania 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
  • REST: określa pola obiektu Route w odpowiedzi, które mają zostać zwrócone. Przed polami należy umieścić prefiks routes., np. routes.distanceMeters.
  • gRPC: określa pola obiektu Route w odpowiedzi, które mają zostać zwrócone.
• Maski pól Compute Route Matrix
  • 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ć, których pól chcesz użyć, i utworzyć dla nich maski pól:

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

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 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 pod polem 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 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 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. 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

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

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.