返す情報を選択する
ルートまたはルート マトリックスを計算するメソッドを呼び出すと、 検索するフィールドをリスト化して、必要な情報を 返されます。返されるフィールドのデフォルト リストはありません。このリストを省略すると、メソッドはエラーを返します。
フィールドリストを指定するには、レスポンス フィールド マスクを作成します。次に、
URL パラメータ $fields
を使用して、いずれかのメソッドのレスポンス フィールドをマスクします。
fields
を使用するか、HTTP または gRPC ヘッダー X-Goog-FieldMask
を使用します。
フィールド マスクの使用は、フィールド マスクを使用して それにより、不要な処理時間と料金を回避できます。
URL パラメータの詳細については、システム パラメータをご覧ください。
レスポンス フィールド マスクを定義する
レスポンス フィールド マスクは、パスのカンマ区切りのリストです。各パスは、レスポンス メッセージ内の一意のフィールドを指定します。パスは最上位のレスポンス メッセージで始まり、 指定したフィールドへのドット区切りパス。
フィールドパスを次のように作成して指定します。
- Routes API から、必要な情報を含むフィールドを検索します。詳細については、フィールドの参照をご覧ください。
- 必要なフィールドのパスを特定し、それらのフィールド マスクを作成します。詳細については、使用するフィールド マスクを決定するをご覧ください。
必要なすべてのフィールドのフィールド マスクを結合し、フィールド マスクをカンマで区切ります。たとえば、ルート レグと各ルート レグ ステップの所要時間をリクエストするには、両方をカンマで区切って入力します(スペースは入力しないでください)。
routes.legs.distanceMeters,routes.legs.steps.duration
フィールドマスクを API リクエストとともに送信する。たとえば、cURL リクエストでは、フィールド マスクを
-H
とX-Goog-FieldMask
で指定します。-H X-Goog-FieldMask: routes.legs.distanceMeters,routes.legs.steps.duration
フィールド参照
フィールド マスクを使用してレスポンスでリクエストできるフィールドを確認するには、次のリストにリンクされた Routes API リファレンスをご覧ください。フィールドは、リファレンスに示すようにキャメルケースで指定します。たとえば、routePreference
です。
これらの参照には、使用可能なフィールドが含まれています。ただし、フィールド マスクの完全なパスを決定するには、フィールドの階層を参照する必要があります。フィールドの階層を取得する方法については、使用するフィールド マスクを決定するをご覧ください。
- ルート フィールド マスクを計算する
- Compute Route Matrix フィールド マスク
- REST: Cloud Storage バケットの レスポンスの本文 返されます。
- gRPC: 返されるレスポンスの RouteMatrixElement オブジェクトのフィールドを指定します。
使用するフィールド マスクを決定する
使用するフィールドを決定し、そのフィールド マスクを作成する方法は次のとおりです。
*
のフィールド マスクを使用してすべてのフィールドをリクエストします。- レスポンスで、必要なフィールドのフィールドの階層を確認します。
次の形式で、前の手順で示したフィールドの階層を使用してフィールド マスクを作成します。
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 が生成されたルートのルートトークンを返すようにリクエストする手順は次のとおりです。
- ルートトークンを返すために必要な次のパラメータを設定します。
travelMode
をDRIVE
に設定する。routingPreference
をTRAFFIC_AWARE
またはTRAFFIC_AWARE_OPTIMAL
に設定します。
- ルートのいずれの地点も
via
地点でないことを確認します。 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 リファレンス。