欧州経済領域（EEA）のデベロッパー

返されるフィールドを選択する

ルートまたはルート マトリックスをリクエストする場合は、フィールド マスクを使用して、レスポンスで返す情報を指定する必要があります。返されるフィールドのデフォルト リストはありません。フィールド マスクを指定しない場合、メソッドはエラーを返します。

フィールド マスクを使用すると、不要なデータをリクエストすることがなくなるため、レスポンスのレイテンシが短縮され、システムに不要な情報が返されるのを防ぐことができます。

必要なフィールドのリストをレスポンス フィールド マスクで指定します。次に、URL パラメータ $fields または fields を使用するか、HTTP または gRPC ヘッダー X-Goog-FieldMask を使用して、レスポンス フィールド マスクをいずれかのメソッドに渡します。

URL パラメータの詳細については、システム パラメータをご覧ください。

レスポンス フィールド マスクを定義する

レスポンス フィールド マスクは、カンマ区切りのパスのリストです。各パスは、レスポンス メッセージ内の一意のフィールドを指定します。パスは、最上位のレスポンス メッセージから始まり、指定されたフィールドへのドット区切りのパスを使用します。

次のようにフィールドパスを作成して指定します。

  1. 必要な情報が含まれているフィールドを見つけます。詳細については、フィールド参照をご覧ください。
  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 の Compute Routes または Compute Route Matrix のリファレンスをご覧ください。リファレンスに示されているように、フィールドをキャメルケースで指定します。例: routePreference

これらのリファレンスには、使用可能なフィールドが含まれています。ただし、完全なフィールド マスクパスを決定するには、フィールドの階層を参照する必要があります。フィールドの階層を取得する方法については、使用するフィールド マスクを決定するをご覧ください。

  • ルート計算のフィールド マスク
    • REST: 返されるレスポンスの Route オブジェクトのフィールドを、routes. を先頭に付けて指定します（例: routes.distanceMeters）。
    • gRPC: レスポンスで返す Route オブジェクトのフィールドを指定します。
  • ルート マトリックスの計算のフィールド マスク

使用するフィールド マスクを決定する

使用するフィールドを決定し、それらのフィールド マスクを作成する方法は次のとおりです。

  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

computeRoutes への gRPC 呼び出し

ルートの計算に使用される gRPC computeRoutes メソッドの場合、レスポンス フィールド マスクを含む変数を設定して、レスポンスでルート distanceMeters、duration、エンコードされたポリライン フィールドを返します。次に、その変数をリクエストに渡します。

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

computeRouteMatrix への gRPC 呼び出し

ルート マトリックスの計算に使用される gRPC computeRouteMatrix メソッドの場合、レスポンス フィールド マスクを含む変数を設定して、出発地と目的地の各組み合わせについて originIndex、destinationIndex、duration を返すように指定します。次に、その変数をリクエストに渡します。

const (
  fieldMask = "originIndex,destinationIndex,duration"
)

フィールドパスに関する考慮事項

必要なフィールドのみを返すには、レスポンスに必要なフィールドのみを含めます。

  • 処理時間を短縮し、結果を返す際のレイテンシを短縮します。
  • 安定したレイテンシ パフォーマンスを確保する。すべてのフィールドを選択した場合、または最上位レベルですべてのフィールドを選択した場合、新しいフィールドが追加されてレスポンスに自動的に含まれると、パフォーマンスが低下する可能性があります。
  • レスポンス サイズが小さくなるため、ネットワーク スループットが向上します。
  • 不要なデータをリクエストしないようにする。これにより、不要な処理時間と請求料金を回避できます。

フィールド マスクの作成方法の詳細については、field_mask.proto をご覧ください。