返す情報を選択する

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

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

フィールド マスキングは、不要なデータをリクエストしないようにするための優れた設計プラクティスです。これにより、不必要な処理時間や課金を回避できます。

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

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

レスポンス フィールド マスクは、パスのカンマ区切りリストです。各パスには、レスポンス メッセージ内の一意のフィールドを指定します。パスは、トップレベルのレスポンス メッセージから始まり、指定されたフィールドへのドット区切りパスを使用します。

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

topLevelField[.secondLevelField][.thirdLevelField][...]
  • Compute ルートのフィールド マスク
    • REST: 返すレスポンスの Route オブジェクトのフィールドを指定します。フィールドには routes. の接頭辞を付けます（例: routes.distanceMeters）。
    • gRPC: 返されるレスポンスの Route オブジェクトのフィールドを指定します。
  • Compute ルート行列のフィールド マスク

フィールド マスクの作成方法について詳しくは、field_mask.proto をご覧ください。

使用するフィールド マスクを決定する

使用するフィールド マスクを指定する方法は次のとおりです。

  1. フィールド マスク * を使用して、すべてのフィールドをリクエストします。
  2. レスポンスのフィールドの階層を確認して、必要なフィールドを決定します。
  3. フィールド階層を使用してフィールド マスクを作成します。

たとえば、交通機関のルートからのこの部分的なレスポンスは、次のようになります。

 "routes": [
  {
    "legs": [
    {
      "distanceMeters": 12886,
    }
...
]}]

distanceMeters フィールドのみを返す場合、フィールド マスクは次のようになります。

routes.legs.distanceMeters

別の例: レスポンスの legs の下にあるすべてを返す場合、フィールド マスクは次のようになります。

routes.legs

フィールドパスを指定します

このセクションでは、レスポンス フィールド マスクの一部としてフィールドパスを指定する方法の例を示します。

computeRoutes に対する REST 呼び出し

最初の例では、computeRoutes メソッドの REST 呼び出しを使用してルートを計算します。この例では、ヘッダーでフィールド マスクを指定し、レスポンスで Route.distanceMeters フィールドと Route.duration フィールドを返します。必ずフィールド名の前に routes を付けるようにしてください。

-H X-Goog-FieldMask: routes.distanceMeters,routes.duration

computeRouteMatrix に対する REST 呼び出し

ルート マトリックスの計算に使用される REST computeRouteMatrix メソッドの場合、ヘッダーで、出発地と目的地の組み合わせごとに originIndex、destinationIndex、duration を返すように指定します。

-H X-Goog-FieldMask: originIndex,destinationIndex,duration

gRPC 呼び出し

gRPC の場合は、レスポンス フィールド マスクを含む変数を設定します。その後、その変数をリクエストに渡すことができます。

const (
  fieldMask = "routes.distanceMeters,routes.duration,routes.polyline.encodedPolyline"
)

フィールドパスに関する考慮事項

必要なフィールドのみをレスポンスに含めます。必要なフィールドだけを返すことができます。

  • 処理時間を短縮して、低レイテンシで結果が返されるようにする。
  • 今後 API でレスポンス フィールドが追加され、それらの新しいフィールドの計算時間が長くなる場合に、安定したレイテンシ パフォーマンスを確保できます。すべてのフィールドを選択した場合や、トップレベルですべてのフィールドを選択した場合、すべての新しいフィールドが自動的にレスポンスに含まれるため、パフォーマンスが低下する可能性があります。
  • レスポンス サイズが小さくなり、ネットワーク スループットが高くなります。
  • 不要なデータをリクエストしないようにします。これにより、不要な処理時間と課金を回避できます。

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

Routes API が生成されたルートのルートトークンを返すようにリクエストするには、ルートトークンを返すための要件を満たし、routes.route_token フィールド マスクを使用してトークンをリクエストします。

  1. travel_mode を DRIVING に設定します。
  2. routing_preference を TRAFFIC_AWARE または TRAFFIC_AWARE_OPTIMAL に設定します。
  3. ルートの地点に via 地点がないことを確認します。
  4. ルートトークンのフィールド マスクを指定します。 
    -H X-Goog-FieldMask: routes.route_token

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

ルートトークンの例

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

terminal
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-FieldMask: routes.route_token,routes.duration,routes.distanceMeters,routes.polyline.encodedPolyline
'https://routes.googleapis.com/directions/v2:computeRoutes'

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