返す情報を選択する

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

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

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

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

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

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

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

topLevelField[.secondLevelField][.thirdLevelField][...]
  • Compute ルートのフィールド マスク
    • REST: 返されるレスポンスの Route オブジェクトのフィールドを指定します。名前の前に routes. を付けます(例: routes.distanceMeters)。
    • gRPC: 返されるレスポンスの Route オブジェクトのフィールドを指定します。
  • Compute Route マトリックスのフィールド マスク

フィールド マスクの作成方法について詳しくは、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 メソッドの場合、ヘッダーで、出発地と目的地の組み合わせごとに originIndexdestinationIndexduration を返すように指定します。

-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_modeDRIVING に設定します。
  2. routing_preferenceTRAFFIC_AWARE または TRAFFIC_AWARE_OPTIMAL に設定します。
  3. ルート上のどの地点も via 地点ではないことを確認します。
  4. ルートトークンのフィールド マスクを指定します。
    -H X-Goog-FieldMask: routes.route_token

計画したルートは 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.route_token,routes.duration,routes.distanceMeters,routes.polyline.encodedPolyline
'https://routes.googleapis.com/directions/v2:computeRoutes'

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