返す情報を選択する
ルートまたはルート マトリックスを計算するメソッドを呼び出すときは、レスポンスで返すフィールドをリストして、必要な情報を指定する必要があります。返されるフィールドのデフォルト リストはありません。このリストを省略すると、メソッドはエラーを返します。
レスポンス フィールド マスクを作成して、フィールド リストを指定します。次に、URL パラメータ $fields
または fields
を使用するか、HTTP ヘッダーまたは gRPC ヘッダー X-Goog-FieldMask
を使用して、いずれかのメソッドにレスポンス フィールド マスクを渡します。
フィールド マスクの使用は、不要なデータをリクエストしないようにするための優れた設計プラクティスです。これにより、不要な処理時間と課金を回避できます。
URL パラメータの詳細については、システム パラメータをご覧ください。
レスポンス フィールド マスクを定義する
レスポンス フィールド マスクは、パスのカンマ区切りのリストです。各パスは、レスポンス メッセージ内の一意のフィールドを指定します。パスは、最上位のレスポンス メッセージから始まり、指定されたフィールドへのドット区切りパスを使用します。
フィールドパスを次のように作成して指定します。
- Routes API から、必要な情報を含むフィールドを検索します。詳しくは、フィールド参照をご覧ください。
- 必要なフィールドのパスを決定し、そのフィールド マスクを作成する: 詳細については、使用するフィールド マスクを決定するをご覧ください。
必要なすべてのフィールドのフィールド マスクを結合し、フィールド マスクをカンマで区切ります。たとえば、ルート区間の
distanceMeters
と、ルート区間の各ステップの所要時間をリクエストするには、両方のルートをスペースを入れずにカンマで区切って入力します。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
です。
これらの参照には、使用可能なフィールドが含まれています。ただし、フィールド マスクの完全なパスを決定するには、フィールドの階層を参照する必要があります。フィールドの階層を取得する方法については、使用するフィールド マスクを決定するをご覧ください。
- コンピューティング ルートのフィールド マスク
- ルート マトリックスのフィールド マスクの計算
- REST: 返されるレスポンスの本文のフィールドを指定します。
- gRPC: レスポンスで返される RouteMatrixElement オブジェクトのフィールドを指定します。
使用するフィールド マスクを決定する
使用するフィールドを決定し、そのフィールド マスクを作成する方法は次のとおりです。
*
のフィールド マスクを使用してすべてのフィールドをリクエストします。- 目的のフィールドのレスポンスに含まれるフィールドの階層を確認します。
前のステップで示したフィールドの階層を使用して、次の形式でフィールド マスクを作成します。
topLevelField[.secondLevelField][.thirdLevelField][...]
たとえば、ルートからの部分レスポンスは次のようになります。
"routes": [ { "legs": [ { "steps": [ {"distanceMeters": 119}, {"distanceMeters": 41} ] } ], "distanceMeters": 160 } ]
ルート区間の distanceMeters
フィールド(前のサンプルの最後の distanceMeters
)のみを返す場合、フィールド マスクは次のようになります。
routes.legs.distanceMeters
代わりに、ルート区間の各ステップ(前のサンプルの steps
の下にある distanceMeters
)で 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 に返すようリクエストする手順は次のとおりです。
- ルートトークンを返すために必要な次のパラメータを設定します。
travelMode
をDRIVE
に設定します。routingPreference
をTRAFFIC_AWARE
またはTRAFFIC_AWARE_OPTIMAL
に設定します。
- ルートのいずれの地点も
via
地点でないことを確認します。 - ルートトークンを返すように
routes.routeToken
フィールド マスクを指定します。X-Goog-FieldMask: routes.routeToken
計画したルートのルートトークンは、Navigation SDK で使用できます。詳細については、ルートを計画する(Android)またはルートを計画する(iOS)をご覧ください。
ルートトークンの例
以下は、1 つの出発地、1 つの目的地のルートに対する 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 リファレンスをご覧ください。