返す情報を選択する

ルートまたはルート マトリックスを計算するメソッドを呼び出すと、 検索するフィールドをリスト化して、必要な情報を 返されます。返されるフィールドのデフォルト リストはありません。このリストを省略すると、メソッドはエラーを返します。

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

フィールド マスクの使用は、フィールド マスクを使用して それにより、不要な処理時間と料金を回避できます。

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

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

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

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

  1. Routes API から、必要な情報を含むフィールドを検索します。詳細については、フィールドの参照をご覧ください。
  2. 必要なフィールドのパスを特定し、それらのフィールド マスクを作成します。詳細については、使用するフィールド マスクを決定するをご覧ください。

  3. 必要なすべてのフィールドのフィールド マスクを結合し、フィールド マスクをカンマで区切ります。たとえば、ルート レグと各ルート レグ ステップの所要時間をリクエストするには、両方をカンマで区切って入力します（スペースは入力しないでください）。

    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: Cloud Storage バケットの 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 呼び出し

最初の例では、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.

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

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 リファレンス。