返す情報を選択する

ルートまたはルート マトリックスを計算するメソッドを呼び出す場合は、レスポンスで返されるフィールドを一覧表示して、必要な情報を指定する必要があります。返されるフィールドのデフォルト リストはありません。このリストを省略すると、メソッドはエラーを返します。

フィールドリストを指定するには、レスポンス フィールド マスクを作成します。次に、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: 返されるレスポンスの Route オブジェクトのフィールドを指定します。接頭辞は routes. です（例: routes.distanceMeters）。
    • gRPC: 返すレスポンスの Route オブジェクトのフィールドを指定します。
  • 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 をご覧ください。

ルートトークンをリクエストする

生成されたルートのルートトークンを Routes API に返すようリクエストする手順は次のとおりです。

  1. ルートトークンを返すために必要な次のパラメータを設定します。
    • travelMode を DRIVE に設定する。
    • routingPreference を TRAFFIC_AWARE または TRAFFIC_AWARE_OPTIMAL に設定します。
  2. ルートのどのウェイポイントも via ウェイポイントではないことを確認します。
  3. routes.routeToken フィールドマスクを指定して、ルートトークンを返します。
    X-Goog-FieldMask: routes.routeToken

計画したルートのルートトークンは、Navigation SDK で使用できます。詳細については、ルートを計画する（Android）またはルートを計画する（iOS）をご覧ください。

ルートトークンの例

以下は、単一の出発地と単一の目的地を持つルートの cURL リクエスト本文の例です。フィールド マスクを使用して、ルート トークン、ルートの所要時間、距離、ルート ポリラインをリクエストしています。

curl -X POST -d
{"origin":{
    "location": {
        "latLng":{
            "latitude":  -37.8167,
            "longitude": 144.9619
        }
    }
},
"destination":{
    "location": {
        "latLng":{
            "latitude":-37.8155,
            "longitude": 144.9663
        }
    }
},
"routingPreference":"TRAFFIC_AWARE",
"travelMode":"DRIVE"
}
-H 'X-Goog-Api-Key: YOUR_API_KEY' \
-H X-Goog-FieldMask: routes.routeToken,routes.duration,routes.distanceMeters,routes.polyline.encodedPolyline
'https://routes.googleapis.com/directions/v2:computeRoutes'

詳細については、Compute Routes API リファレンスをご覧ください。