エンドポイント プロパティのリファレンス

Apigee X のドキュメントを表示中です。
Apigee Edge のドキュメントを表示する。

このトピックでは、トランスポート プロパティについて説明します。トランスポート プロパティは、メッセージングと接続動作を制御するために TargetEndpoint 構成と ProxyEndpoint 構成で設定できます。TargetEndpointProxyEndpoint の構成オプションの詳細については、API プロキシ構成リファレンスをご覧ください。

TargetEndpoint トランスポート プロパティ

TargetEndpoint 構成の HTTPTargetConnection 要素は、一連の HTTP トランスポート プロパティを定義します。これらのプロパティは、トランスポート レベルの構成を設定するのに使用できます。

プロパティは、次の構成例に示すように TargetEndpoint HTTPTargetConnection 要素で設定されます。

<TargetEndpoint name="default">
  <HTTPTargetConnection>
    <URL>http://mocktarget.apigee.net</URL>
    <Properties>
      <Property name="request.retain.headers">User-Agent,Referer,Accept-Language</Property>
      <Property name="retain.queryparams">apikey</Property>
    </Properties>
  </HTTPTargetConnection>
</TargetEndpoint>

TargetEndpoint トランスポート プロパティの仕様

プロパティ名 デフォルト値 説明
allow.tls.session.resumption はい true(デフォルト)の場合、クライアントはターゲットへ新しい接続を行う際に、TLS セッションを再利用します。TLS セッションの再利用を希望しない場合は、false に設定します。一般的に、セッションの再利用は接続時間が短いことを意味しますが、一部のターゲットではセッションの再利用がサポートされていない場合や、使用しにくい場合があります。
keepalive.timeout.millis 60000 接続プール内のターゲット接続の接続アイドル タイムアウト。プール内の接続が指定した上限時間を超えてアイドル状態にあると、その接続は閉じられます。
connect.timeout.millis

3000

ターゲット接続のタイムアウト。接続タイムアウトが発生すると、Apigee は HTTP 503 ステータス コードを返します。

io.timeout.millis 55000

指定したミリ秒間に読み取るデータが存在しない場合、または指定したミリ秒間にソケットでデータ書き込みの準備ができていない場合に、トランザクションはタイムアウトとして処理されます。

  • HTTP リクエストの書き込み中にタイムアウトが発生した場合、408 Request Timeout が返されます。
  • HTTP レスポンスの読み取り中にタイムアウトが発生した場合、504 Gateway Timeout が返されます。

io.timeout.millis および api.timeout の設定をご覧ください。

supports.http11 はい これが true のときにクライアントが 1.1 のリクエストを送信すると、ターゲットにも 1.1 のリクエストが送信されます。それ以外の場合は 1.0 のリクエストがターゲットに送信されます。
use.proxy はい

このプロパティは Apigee ハイブリッドにのみ適用されます。

API プロキシのフォワード プロキシを構成するで説明されているとおり、Apigee ハイブリッド オーバーライド ファイルに HTTP_PROXY 構成が含まれている場合は、このプロパティを使用して、どのプロキシがそのプロキシ構成を使用しないようにするかについて、管理と制御を行います。

false に設定すると、API プロキシは、プロキシで設定されたターゲット接続に対して、Apigee ハイブリッド オーバーライド ファイルで指定された HTTP プロキシ構成をスキップします。

use.proxy.tunneling はい

このプロパティは Apigee ハイブリッドにのみ適用されます。

これを true に設定し、API プロキシのフォワード プロキシを構成するで説明されているように、プロキシ構成が指定された Apigee ハイブリッド オーバーライド ファイルである場合、指定したトンネルを使用するようにターゲット接続が設定されます。ターゲットが TLS / SSL を使用する場合、このプロパティは無視され、メッセージは常にトンネルを使用して送信されます。

request.streaming.enabled false

デフォルト(false)では、HTTP リクエストのペイロードがバッファに読み込まれ、ペイロード上で動作可能なポリシーが予期どおりに機能します。ペイロードがバッファのサイズ(Apigee では 10 MB)より大きい場合は、この属性を true に設定できます。true の場合、HTTP リクエストのペイロードはバッファに読み込まれません。そのままターゲットのエンドポイントにストリーミングされます。これに該当する場合、TargetEndpoint リクエスト フローのペイロードで動作するポリシーのすべてがバイパスされます。リクエストとレスポンスのストリーミングもご覧ください。

response.streaming.enabled false

デフォルト(false)では、HTTP レスポンスのペイロードがバッファに読み込まれ、ペイロード上で動作可能なポリシーが予期どおりに動作します。ペイロードがバッファのサイズ(Apigee では 10 MB)より大きい場合は、この属性を true に設定できます。true の場合、HTTP レスポンスのペイロードはバッファに読み込まれません。そのまま ProxyEndpoint のレスポンス フローにストリーミングされます。これに該当する場合、TargetEndpoint レスポンス フローのペイロードで動作するポリシーのすべてがバイパスされます。リクエストとレスポンスのストリーミングもご覧ください。

success.codes 該当なし

デフォルトでは、Apigee は HTTP コード 4XX5XX をエラーとして処理し、HTTP コード 1XX2XX3XX を成功とみなします。このプロパティを使用すると、成功コードを明示的に定義できます。たとえば、2XX, 1XX, 505 では 100200505 の HTTP レスポンス コードはすべて成功とみなされます。

このプロパティを設定すると、デフォルト値が上書きされます。このため、デフォルトの成功コードのリストに HTTP コード 400 を追加する場合は、このプロパティを次のように設定します。

<Property name="success.codes">1xx,2xx,3xx,400</Property>

HTTP コード 400 のみを成功コードとみなす場合は、このプロパティを次のように設定します。

<Property name="success.codes">400</Property>

HTTP コード 400 を唯一の成功コードとして設定すると、HTTP コード 1xx2xx3xx は失敗とみなされます。

compression.algorithm 該当なし デフォルトでは、Apigee は受信したメッセージに設定された圧縮タイプ(gzip、deflate、なし)を使用します。たとえば gzip 圧縮を使用してクライアントからリクエストを受信した場合、Apigee も gzip 圧縮を使用してリクエストをターゲットに転送します。ターゲットから受信したレスポンスで deflate が使用されている場合は、Apigee も deflate を使用してクライアントにレスポンスを転送します。サポートされている値は次のとおりです。
  • gzip:: 常に gzip 圧縮を使用してメッセージを送信します
  • DEFLATE: 常に DEFLATE 圧縮を使用してメッセージを送信します
  • none: 常に圧縮なしでメッセージを送信します

Apigee は、GZIP / DEFLATE 圧縮を使用した圧縮と解凍もサポートしていますかをご覧ください。

request.retain.headers.
enabled
はい デフォルトでは、Apigee は送信メッセージ上のすべての HTTP ヘッダーを常に保持します。true に設定すると、受信リクエストに含まれるすべての HTTP ヘッダーが送信リクエストに設定されます。
request.retain.headers なし ターゲット サービスへの送信リクエストに設定する必要があるリクエストからの特定の HTTP ヘッダーを定義します。たとえば、User-Agent ヘッダーを「パススルー」するには、request.retain.headers の値を User-Agent に設定します。複数の HTTP ヘッダーは、User-Agent,Referer,Accept-Language のようにカンマ区切りのリストとして指定します。このプロパティは request.retain.headers.enabled をオーバーライドします。request.retain.headers.enabledfalse に設定されている場合でも、request.retain.headers プロパティで指定されたヘッダーは送信メッセージに設定されます。
response.retain.headers.
enabled
はい デフォルトでは、Apigee は送信メッセージ上のすべての HTTP ヘッダーを常に保持します。true に設定すると、ターゲット サービスからの受信レスポンスに含まれるすべての HTTP ヘッダーが、ProxyEndpoint に渡される前に送信レスポンス上に設定されます。
response.retain.headers 該当なし ProxyEndpoint に渡される前に送信レスポンスに設定する必要があるレスポンスからの特定の HTTP ヘッダーを定義します。たとえば、Expires ヘッダーを「パススルー」にするには、response.retain.headers の値を Expires に設定します。複数の HTTP ヘッダーは、Expires,Set-Cookie のようにカンマ区切りのリストとして指定します。このプロパティは response.retain.headers.enabled をオーバーライドします。response.retain.headers.enabledfalse に設定されている場合でも、response.retain.headers プロパティで指定されたヘッダーは送信メッセージに設定されます。
retain.queryparams.
enabled
はい デフォルトでは、Apigee は送信リクエスト上のすべてのクエリ パラメータを常に保持します。true に設定すると、受信リクエストに含まれるすべてのクエリ パラメータが、ターゲット サービスへの送信リクエストに設定されます。
retain.queryparams なし 送信リクエストに設定する特定のクエリ パラメータを定義します。たとえば、リクエスト メッセージのクエリ パラメータ apikey を含めるには、retain.queryparamsapikey に設定します。複数のクエリ パラメータは、apikey,environment のようにカンマ区切りのリストとして指定します。このプロパティは、retain.queryparams.enabled をオーバーライドします。

ProxyEndpoint トランスポート プロパティ

ProxyEndpoint HTTPTargetConnection 要素は、HTTP トランスポート プロパティのセットを定義します。これらのプロパティは、トランスポート レベルの構成の設定に使用できます。

プロパティは、次の構成例に示すように ProxyEndpoint HTTPProxyConnection 要素で設定されます。

<ProxyEndpoint name="default">
  <HTTPProxyConnection>
    <BasePath>/v1/weather</BasePath>
    <Properties>
      <Property name="request.streaming.enabled">true</Property>
    </Properties>
  </HTTPProxyConnection>
</ProxyEndpoint>

ProxyEndpoint トランスポート プロパティの仕様

プロパティ名 デフォルト値 説明
X-Forwarded-For false true に設定すると、仮想ホストの IP アドレスが HTTP の X-Forwarded-For ヘッダーの値として送信リクエストに追加されます。
request.streaming.
enabled
false デフォルト(false)では、HTTP リクエストのペイロードがバッファに読み込まれ、ペイロード上で動作可能なポリシーが予期どおりに機能します。ペイロードがバッファサイズ(Apigee では 10 MB)より大きい場合は、この属性を true に設定できます。true の場合、HTTP リクエストのペイロードはバッファに読み込まれません。そのまま TargetEndpoint のリクエスト フローにストリーミングされます。これに該当する場合、ProxyEndpoint リクエスト フローのペイロードで動作するポリシーのすべてがバイパスされます。リクエストとレスポンスのストリーミングもご覧ください。
response.streaming.
enabled
false デフォルト(false)では、HTTP レスポンスのペイロードがバッファに読み込まれ、ペイロード上で動作可能なポリシーが予期どおりに動作します。ペイロードがバッファサイズ(Apigee では 10 MB)より大きい場合は、この属性を true に設定できます。true の場合、HTTP レスポンスのペイロードはバッファに読み込まれません。そのままクライアントにストリーミングされます。これに該当する場合、ProxyEndpoint レスポンス フローのペイロードで動作するポリシーのすべてがバイパスされます。リクエストとレスポンスのストリーミングもご覧ください。
compression.algorithm 該当なし

デフォルトでは、Apigee は受信したメッセージに対して設定された圧縮タイプ(gzip、deflate、なし)を使用します。たとえば、クライアントが gzip 圧縮を使用するリクエストを送信した場合、Apigee も gzip 圧縮を使用してターゲットにリクエストを転送します。TargetEndpoint または ProxyEndpoint でこのプロパティを設定することで、圧縮アルゴリズムが明示的に適用されるように構成できます。サポートされている値は次のとおりです。

  • gzip:: 常に gzip 圧縮を使用してメッセージを送信します
  • DEFLATE: 常に DEFLATE 圧縮を使用してメッセージを送信します
  • none: 常に圧縮なしでメッセージを送信します

Apigee は、GZIP / DEFLATE 圧縮を使用した圧縮と解凍もサポートしていますかをご覧ください。

api.timeout 該当なし

個々の API プロキシにタイムアウトを構成する(ミリ秒単位)

ストリーミングが有効にされている API プロキシも含め、指定した時間が経過すると 504 Gateway Timeout ステータスでタイムアウトするように API プロキシを構成できます。

たとえば、180,000 ミリ秒(3 分)後にタイムアウトするようにプロキシを構成するには、次のプロパティを HTTPTargetConnection に追加します。


<Property name="api.timeout">180000</Property>

このプロパティを変数で設定することはできません。

io.timeout.millis および api.timeout の設定をご覧ください。

HTTPHeader.allowDuplicates 該当なし

この設定を使用すると、(特定のヘッダーに対して)重複するヘッダーを許可できます。


<HTTPProxyConnection>
  <Properties>
     <property name = "HTTPHeader.allowDuplicates" value = "Content-Type,Authorization"/>
  </Properties>
</HTTPProxyConnection>
HTTPHeader.multiValued 該当なし

この設定を使用すると、(特定のヘッダーに対して)重複するヘッダーを許可できます。


<HTTPProxyConnection>
  <Properties>
    <property name = "HTTPHeader.multiValued" value = "Content-Type,Authorization"/>
  </Properties>
</HTTPProxyConnection>

io.timeout.millis および api.timeout の設定

io.timeout.millisapi.timeout のオペレーションは関連しています。API プロキシに対するすべてのリクエストでの動作は次のようになります。

  1. Ingress(別名内部ロードバランサ)は、タイムアウト値を Message Processor に送信します。このタイムアウト値はデフォルトで 300 秒に設定され、構成することはできません。
  2. Message Processor では、api.timeout が設定されます。
    1. api.timeout がプロキシレベルで設定されていない場合は、Ingress によって設定されたタイムアウトを使用します。
    2. api.timeout がプロキシレベルで設定されている場合は、Message Processor で Ingress タイムアウトまたは api.timeout の値よりも小さい値に設定します。
  3. api.timeout の値によって、API リクエストからレスポンスまでの API プロキシの最大実行時間が指定されます。

    Message Processor は API プロキシ内で各ポリシーが実行された後、またはターゲット エンドポイントにリクエストを送信する前に、api.timeout の値からリクエスト開始時以降の経過時間を差し引いて残り時間を計算します。

    算出された値が 0 未満の場合、リクエストを処理するための最大許容時間が満了しているため、Message Processor によって 504 Gateway Timeout が返されます。

  4. io.timeout.millis の値によって、ターゲット エンドポイントが応答するまでの最大許容時間が指定されます。

    ターゲット エンドポイントに接続する前に、Message Processor によって api.timeout の値からリクエストの開始からの経過時間を差し引いた値と io.timeout.millis の値のどちらが小さいかを判別します。次に、io.timeout.millis がその値に設定されます。

    • HTTP リクエストの書き込み中にタイムアウトが発生した場合、408 Request Timeout が返されます。
    • HTTP レスポンスの読み取り中にタイムアウトが発生した場合、504 Gateway Timeout が返されます。