タイムアウトと期限を構成する

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

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

タイムアウトとデッドラインを構成すると、次の方法で処理時間を管理できます。

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

タイムアウトとデッドラインのニーズを理解する

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

次のガイドラインを参考に、目的に合った設定を使用しているかどうかを確認してください。

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

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

別の Tab で図式を開く

timeout パラメータを設定する

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

duration プロトコル バッファを使用して 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 45s 1990 年代 180 秒
1,001 ～ 10,000 120 秒 360s 900 秒
10,001 以上 60 秒 + 10,000 件の配送ごとに 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 の最大リクエスト時間です。リクエスト本文の timeout プロパティのみを設定して、解決時間を構成します。

タイムアウトとデッドラインに影響するパラメータ

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

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

allowLargeDeadlineDespiteInterruptionRisk

allowLargeDeadlineDespiteInterruptionRisk パラメータは、リクエストの最大期限を 3,600 秒に増やします。このパラメータが設定されていない場合、timeout パラメータと deadline パラメータの最大値は 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 サンプル リクエスト

次の例は、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)