반환할 필드 선택

경로 또는 경로 매트릭스를 요청할 때는 필드 마스크를 사용하여 응답이 반환해야 하는 정보를 지정해야 합니다. 반환되는 필드의 기본 목록은 없습니다. 필드 마스크를 지정하지 않으면 메서드에서 오류를 반환합니다.

필드 마스크를 사용하면 불필요한 데이터를 요청하지 않아도 되므로 응답 지연 시간을 줄이고 시스템에 필요하지 않은 정보에 대한 불필요한 요금을 피할 수 있습니다.

응답 필드 마스크에 필요한 필드 목록을 지정합니다. 그런 다음 URL 매개변수 $fields 또는 fields를 사용하거나 HTTP 또는 gRPC 헤더 X-Goog-FieldMask를 사용하여 응답 필드 마스크를 메서드에 전달합니다.

URL 매개변수에 관한 자세한 내용은 시스템 매개변수를 참고하세요.

응답 필드 마스크 정의

응답 필드 마스크는 쉼표로 구분된 경로 목록으로, 각 경로는 응답 메시지의 고유한 필드를 지정합니다. 경로는 최상위 응답 메시지에서 시작하며 지정된 필드까지 점으로 구분된 경로를 사용합니다.

다음과 같이 필드 경로를 구성하고 지정합니다.

  1. Routes API에서 필요한 정보가 포함된 필드를 찾습니다. 자세한 내용은 필드 참조를 참고하세요.
  2. 필요한 필드의 경로를 확인하고 필드 마스크를 구성합니다. 자세한 내용은 사용할 필드 마스크 결정을 참고하세요.

  3. 필요한 모든 필드의 필드 마스크를 결합하고 필드 마스크를 쉼표로 구분합니다. 예를 들어 경로 구간의 distanceMeters와 각 경로 구간 단계의 시간을 요청하려면 두 항목을 모두 쉼표로 구분하고 공백 없이 입력합니다.

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

  4. API 요청과 함께 필드 마스크 전송 예를 들어 cURL 요청에서 -H 및 X-Goog-FieldMask를 사용하여 필드 마스크를 지정합니다.

    -H X-Goog-FieldMask: routes.legs.distanceMeters,routes.legs.steps.duration
예시와 자세한 내용은 다음 섹션을 참고하세요.

필드 참조

필드 마스크를 통해 응답에서 요청할 수 있는 필드를 보려면 다음 목록에 링크된 Routes API 참조를 참고하세요. 참조에 표시된 대로 필드를 케멜케이스로 지정합니다. 예를 들면 routePreference입니다.

이러한 참조에는 사용 가능한 필드가 포함되지만 전체 필드 마스크 경로를 확인하려면 필드의 계층 구조를 참고해야 합니다. 필드 계층 구조를 가져오는 방법에 관한 자세한 내용은 사용할 필드 마스크 결정하기를 참고하세요.

  • 경로 필드 마스크 계산
    • REST: 반환할 응답의 경로 객체 필드를 지정합니다(routes. 접두사 사용, 예: routes.distanceMeters).
    • gRPC: 반환할 응답의 경로 객체 필드를 지정합니다.
  • Compute Route Matrix 필드 마스크

사용할 필드 마스크 결정

다음은 사용할 필드를 결정하고 필드 마스크를 구성하는 방법입니다.

  1. 필드 마스크 *를 사용하여 모든 필드를 요청합니다.
  2. 원하는 필드의 응답에서 필드의 계층 구조를 확인합니다.

  3. 다음 형식을 사용하여 이전 단계에 표시된 필드의 계층 구조를 사용하여 필드 마스크를 구성합니다.

    topLevelField[.secondLevelField][.thirdLevelField][...]

예를 들어 경로의 부분 응답은 다음과 같습니다.

"routes": [
    {
        "legs": [
            {  "steps": [
                    {"distanceMeters": 119},
                    {"distanceMeters": 41}  ]
            }
        ],
        "distanceMeters": 160
    }
]

경로 구간의 distanceMeters 필드(즉, 위 샘플의 마지막 distanceMeters)만 반환하려면 필드 마스크가 다음과 같습니다.

routes.legs.distanceMeters

대신 경로 구간의 각 단계에 대한 distanceMeters 필드(즉, 위 샘플의 steps 아래에 있는 distanceMeters)를 반환하려면 필드 마스크가 다음과 같습니다.

routes.legs.steps.distanceMeters

위의 결과와 함께 둘 다 반환하려면 필드 마스크가 다음과 같습니다.

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

필드 마스크 경로의 예

이 섹션에는 REST 및 gRPC 호출에서 필드 경로를 응답 필드 마스크의 일부로 지정하는 방법에 관한 추가 예시가 포함되어 있습니다.

computeRoutes에 대한 REST 호출

첫 번째 예에서는 computeRoutes 메서드에 대한 REST 호출을 사용하여 경로를 계산합니다. 이 예에서는 헤더에서 필드 마스크를 지정하여 응답에 경로 distanceMeters 및 duration 필드를 반환합니다. 필드 이름 앞에 routes를 붙여야 합니다.

X-Goog-FieldMask: routes.distanceMeters,routes.duration

computeRouteMatrix에 대한 REST 호출

경로 매트릭스를 계산하는 데 사용되는 REST computeRouteMatrix 메서드의 경우 헤더에서 출발지와 목적지의 각 조합에 대해 originIndex, destinationIndex, duration를 반환하도록 지정합니다.

X-Goog-FieldMask: originIndex,destinationIndex,duration

gRPC 호출

gRPC의 경우 응답 필드 마스크가 포함된 변수를 설정합니다. 그런 다음 이 변수를 요청에 전달할 수 있습니다.

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

필드 경로 고려사항

필요한 필드만 반환하도록 응답에 필요한 필드만 포함합니다.

  • 처리 시간을 줄여 결과가 더 짧은 지연 시간으로 반환됩니다.
  • 안정적인 지연 시간 성능을 보장합니다. 모든 필드를 선택하거나 최상위 수준에서 모든 필드를 선택하면 새 필드가 추가된 후 응답에 자동으로 포함될 때 성능이 저하될 수 있습니다.
  • 응답 크기가 작아지므로 네트워크 처리량이 증가합니다.
  • 불필요한 데이터를 요청하지 않도록 합니다. 이렇게 하면 불필요한 처리 시간과 요금이 청구되지 않습니다.

필드 마스크 구성에 관한 자세한 내용은 field_mask.proto를 참고하세요.