タイムアウトと期限

このドキュメントでは、Route Optimization API リクエストのタイムアウトと期限の設定を構成する方法について説明します。これらの値を設定しないか、誤って設定すると、接続やレスポンスの品質に関する問題が発生する可能性があります。

タイムアウトはリクエストの本文で定義し、期限はリクエストのヘッダーで定義します。Route Optimization API は、これらのパラメータで定義された制限時間内にリクエストを処理し、最短時間を尊重します。

タイムアウトと期限を構成すると、次の方法で処理時間を管理できます。

  • 処理時間を増やす:
    • 複雑度の高いリクエストを解決します。
    • より質の高い回答を得る。
  • 処理時間を短縮する:
    • 複雑性の低いリクエストをデフォルトよりも速く解決します。
    • リクエストを短時間で解決できますが、レスポンスの品質は低くなります。

注: タイムアウト パラメータと期限パラメータは、solvingMode がデフォルト値の DEFAULT_SOLVE に設定されている場合にのみ適用されます。VALIDATE_ONLY、DETECT_SOME_INFEASIBLE_SHIPMENTS、TRANSFORM_AND_RETURN_REQUEST などの他の solvingMode オプションは、通常、大幅に高速であるため、タイムアウトの調整は必要ありません。

タイムアウトと期限のニーズを理解する

タイムアウトと期限を構成する前に、このセクションを確認して、エンドポイントとプロトコルの選択がこれらの設定にどのように影響するかを理解してください。

次のガイドラインは、目標に合った設定を使用しているかどうかを確認するうえで役立ちます。

  • 継続的かつ繰り返しリクエストや、解決時間が長いほどメリットがある複雑なリクエストには、ノンブロッキング エンドポイントを使用します。
  • 品質のトレードオフを受け入れて、小さなリクエストと結果の迅速な配信にはブロッキング エンドポイントを使用します。
  • 日常のワークフロー（特に本番環境アプリケーション）には gRPC: を使用します。
  • テスト、試験運用、1 回限りのリクエストには REST を使用します。

下のボタンをクリックすると、このドキュメントのどのセクションが設定に最も関連しているかを判断するのに役立つ図が表示されます。

図を別のタブで開く

timeout パラメータを設定する

リクエストの本文で timeout パラメータの値を設定して、サーバーがレスポンスを返す前にリクエストを処理する最大時間を指定します。API が割り当てられた最大時間に達する前に最適なソリューションを見つけた場合、実際に費やされる時間は割り当てられた時間よりも短くなることがあります。

期間プロトコル バッファを使用して timeout パラメータを設定します。これは、1 秒から 1,800 秒までの範囲の秒単位の期間です。allowLargeDeadlineDespiteInterruptionRisk を使用して、この値を最大 3,600 秒まで増やします。

次の表に、リクエストの複雑さ、配送数、車両数に基づいて推奨される timeout の値を示します。

配送と車両の数 制約なし 時間枠と積載量の制約が緩い、またはルートが長い 時間枠が狭い、積載量の制約がある、制約が複雑である、ルートが非常に長い
1 - 8 2 秒 2 秒 5 秒
9 - 32 5 秒 10 秒 20 秒
33 - 100 15 秒 30 秒 60 秒
101 ～ 1,000 45 秒 1990 年代 180 秒
1,001 ～ 10,000 人 120 秒 360 秒 900 年代
10,001 人以上 1 万件の配送あたり 60 秒 + 120 秒 1 万件の配送あたりの 360 件数 1 万件の配送あたり 900 件

期限を設定する

リクエスト ヘッダーに期限を設定して、Route Optimization API がリクエストの処理に費やす最大時間を定義します。以降のサブセクションでは、REST リクエストと gRPC リクエストの期限を設定する方法について説明します。

REST リクエスト

REST を使用してブロッキング エンドポイントを呼び出す場合、デフォルトの 60 秒を超えて期限を延長できます。複雑なリクエストの場合、このデフォルト値では短すぎる場合があります。リクエスト本文でより長い制限時間を指定している場合でも、この操作を行う必要があります。これは、デフォルトの制限時間が、リクエスト本文で設定された 60 秒を超える timeout 値をオーバーライドするためです。

X-Server-Timeout リクエスト ヘッダーを設定して、デフォルトの 60 秒を超える制限時間を延長します。リクエスト本文とは異なり、ヘッダーの値は秒数ですが、接尾辞「s」は付きません。このヘッダーに設定できる最大値は、timeout パラメータの制限に沿ったものになります。

次のコードサンプルは、X-Server-Timeout が 1,800 秒に設定された HTTP ヘッダーを示しています。

curl -X POST 'https://routeoptimization.googleapis.com/v1/projects/:optimizeTours' \
-H "Content-Type: application/json" \
-H "X-Server-Timeout: 1800" \
-H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
--data @- << EOM
{
  "model": {
    ...
  }
}
EOM

クライアント ライブラリと gRPC リクエスト

クライアント ライブラリまたは gRPC を使用する場合は、期限を構成する必要はありません。これらを使用する場合のデフォルトの期限は 3, 600 秒です。これは、この API の最大リクエスト時間です。リクエストの本文でタイムアウト プロパティのみを設定して、解決時間を構成します。

タイムアウトと期限に影響するパラメータ

次のパラメータは、タイムアウトと期限の両方の機能に影響します。

  • allowLargeDeadlineDespiteInterruptionRisk を使用して、リクエストの最大期限を制御します。
  • searchMode を使用して、ソリューションの品質とレイテンシのバランスを取りながら、検索の動作を定義します。

allowLargeDeadlineDespiteInterruptionRisk

allowLargeDeadlineDespiteInterruptionRisk パラメータは、最大リクエスト期限を 3,600 秒に増やします。このパラメータが設定されていない場合、タイムアウト パラメータと期限パラメータの両方の最大値は 1, 800 秒です。

allowLargeDeadline DespiteInterruptionRisk を true に設定して、タイムアウト パラメータと期限パラメータの値を最大 3,600 秒まで増やします。

allowLargeDeadline DespiteInterruptionRisk に指定できる値は次のとおりです。

  • true: 中断のリスクを認識しながら、タイムアウト パラメータと期限パラメータの最大値を 3,600 秒に増やします。
  • false（デフォルト）: タイムアウト パラメータと期限パラメータの最大値 1,800 秒を維持します。

3, 600 秒を超えるタイムアウトが必要な場合は、Google 担当者にお問い合わせください。

searchMode

searchMode パラメータは、オプティマイザーがソリューションを検索する方法を制御します。これにより、迅速なレスポンス（レイテンシの短縮）と高品質のソリューションのどちらを優先するかを指定できます。

ソリューションの品質を優先すると、オプティマイザーは高品質のソリューションを見つけるのにかなりの時間を要します。このような長いリクエストの場合は、タイムアウトを長く設定し、ノンブロッキング エンドポイントを使用して接続の問題を回避することを検討してください。

searchMode に指定できる値は次のとおりです。

  • SEARCH_MODE_UNSPECIFIED（デフォルト）: 未指定の検索モード。RETURN_FAST と同等。
  • RETURN_FAST: 最初の適切な解決策が見つかったら検索を停止します。
  • CONSUME_ALL_AVAILABLE_TIME: 使用可能なすべての時間を費やして、より良い解決策を探します。最適なソリューションが早期に見つかった場合、API は利用可能な時間をすべて使用しません。

キープアライブ ping を有効にする

タイムアウトが 60 秒を超えるブロッキング エンドポイントにリクエストを行う場合、キープアライブ ping は、レスポンスを待機している間の接続の切断を防ぐのに役立ちます。キープアライブ ping は、接続アクティビティを維持し、接続の切断を検出して防止するために送信される小さなパケットです。

使用する API プロトコルに基づいて、これらのパラメータを構成します。

  • REST: TCP 接続レベルでキープアライブを構成します。
  • gRPC: 基盤となる TCP ソケットまたは gRPC プロトコルで直接、キープアライブ ping を構成します。

以降のセクションでは、両方のプロトコルでキープアライブ ping を設定する方法について説明します。

REST キープアライブ

REST を使用する場合のキープアライブ ping の構成は、HTTP クライアント ライブラリによって異なります。curl などのクライアント ライブラリとツールでは、特定の構成オプションが用意されている場合や、自動的に ping が有効になる場合があります。

ライブラリが基盤となる TCP ソケットを公開している場合は、SO_KEEPALIVE などのオプションを使用して、TCP ソケットでキープアライブ ping を直接構成できます。これを行うには、setsockopt() などの関数または同等の関数を使用します。

この GitHub でホストされている関数は、Python の組み込み HTTP クライアントでこの設定を正しく行う方法を示しています。

TCP レベルのキープアライブの詳細については、TLDP キープアライブの概要または HTTP クライアント ライブラリのドキュメントをご覧ください。

gRPC キープアライブ

gRPC は、プロトコルの一部として独自の組み込みキープアライブ メカニズムを提供します。クライアント言語でこの設定を行う方法については、gRPC キープアライブ ガイドをご覧ください。

注: gRPC サーバーは、過剰な数の ping を送信するクライアントを拒否する可能性があります。キープアライブ ping の頻度を高く設定しすぎないようにします。

キープアライブを含む gRPC サンプル リクエスト

次の例は、Python クライアント ライブラリと gRPC レベルのキープアライブ ping を使用して optimizeTours リクエストを行う方法を示しています。

from google.maps import routeoptimization_v1 as ro
from google.maps.routeoptimization_v1.services.route_optimization.transports import grpc as grpc_transport
import sys

_REQUEST_TIMEOUT_SECONDS = 1800
_KEEPALIVE_PING_SECONDS = 30

def create_channel(*args, **kwargs):
  raw_options = kwargs.pop("options", ())
  options = dict(raw_options)
  options["grpc.keepalive_time_ms"] = _KEEPALIVE_PING_SECONDS * 1000
  options["grpc.keepalive_timeout_ms"] = 5000
  # Allow any number of pings between the request and the response.
  options["grpc.http2.max_pings_without_data"] = 0
  print(f"Using options: {options}", file=sys.stderr)
  return grpc_transport.RouteOptimizationGrpcTransport.create_channel(
      *args,
      options=list(options.items()),
      **kwargs,
  )

def create_grpc_transport(*args, **kwargs):
  if "channel" in kwargs:
    raise ValueError(
        "`channel` is overridden by this function, and must not be provided."
    )
  return grpc_transport.RouteOptimizationGrpcTransport(
      *args,
      channel=create_channel,
      **kwargs,
  )

def run_optimize_tours(request):
  client = ro.RouteOptimizationClient(transport=create_grpc_transport)
  return client.optimize_tours(request, timeout=_REQUEST_TIMEOUT_SECONDS)