欧州経済領域（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 のルートの計算またはルート マトリックスの計算のリファレンスをご覧ください。リファレンスに示すように、フィールドはキャメルケースで指定します。例: 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 呼び出し

最初の例では、REST 呼び出しを使用して computeRoutes メソッドを呼び出し、 ルートを計算します。この例では、ヘッダーでフィールド マスクを指定して、レスポンスでルートの 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 をご覧ください。