Programiści z Europejskiego Obszaru Gospodarczego (EOG)

Wybieranie pól do zwrócenia

Gdy wysyłasz prośbę o trasę lub macierz tras, musisz użyć maski pól, aby określić, jakie informacje powinny zostać zwrócone w odpowiedzi. Nie ma domyślnej listy zwracanych pól. Jeśli nie określisz maski pól, metody zwrócą błąd.

Użycie maski pól 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 pól odpowiedzi. Następnie przekazujesz maskę pól 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 pól odpowiedzi

Maska pól odpowiedzi to lista ścieżek rozdzielonych przecinkami. 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 rozdzielonej 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 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 pól, 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 etapu trasy oraz czas trwania każdego kroku etapu trasy, wpisz je oba, rozdzielając je przecinkiem i bez spacji:

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

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

    -H X-Goog-FieldMask: routes.legs.distanceMeters,routes.legs.steps.duration
Przykłady i więcej informacji znajdziesz w tych sekcjach.

Odwołania do pól

Aby zobaczyć pola, o które możesz poprosić w odpowiedzi za pomocą masek pól, zapoznaj się z odwołaniami do interfejsu Routes API Compute Routes lub Compute Route Matrix, które znajdziesz na tej liście. Pola określaj w notacji camel case, jak pokazano w odwołaniu. Na przykład routePreference.

Te odwołania zawierają dostępne pola, ale aby określić pełną ścieżkę maski pól, musisz zapoznać się z hierarchią pól. Więcej informacji o uzyskiwaniu hierarchii pól znajdziesz w artykule Określanie maski pól, której chcesz użyć.

  • Maska pól 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 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 utworzyć dla nich maski pól:

  1. Poproś o wszystkie pola , używając maski pól *.
  2. Sprawdź hierarchię pól w odpowiedzi na pola, które Cię interesują.

  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 distanceMeters w poprzednim przykładzie, maska pól 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 pól będzie wyglądać tak:

routes.legs.steps.distanceMeters

Jeśli chcesz zwrócić oba te pola, maska pól 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 pól 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ć do nazwy pola 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, 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ę pól 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ę pól 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ędniaj 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 zostaną dodane 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 pól znajdziesz w field_mask.proto.