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

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

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

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

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

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

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

プロパティ名 デフォルト値 説明
keepalive.timeout.millis 60000 接続プール内のターゲット接続の接続アイドル タイムアウト。プール内の接続が指定した上限時間を超えてアイドル状態にあると、その接続は閉じられます。
connect.timeout.millis

3000

ターゲット接続のタイムアウト。接続タイムアウトが発生すると、Edge から HTTP 503 ステータスが返されます。
io.timeout.millis 55000

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

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

この値は必ず、仮想ホストの proxy_read_timeout プロパティの値より小さくする必要があります。

Private Cloud のお客様は、この値を、Router が Message Processor との通信に使用するタイムアウト値より小さくする必要があります。詳しくは、Router のタイムアウトの構成をご覧ください。

詳しくは、Edge Cloud の io.timeout.millis および api.timeout の設定をご覧ください。
supports.http10 true これが true のときにクライアントが 1.0 のリクエストを送信すると、ターゲットにも 1.0 のリクエストが送信されます。それ以外の場合は 1.1 のリクエストがターゲットに送信されます。
supports.http11 true これが true のときにクライアントが 1.1 のリクエストを送信すると、ターゲットにも 1.1 のリクエストが送信されます。それ以外の場合は 1.0 のリクエストがターゲットに送信されます。
use.proxy true true に設定され、プロキシ構成が http.properties で指定されている場合（オンプレミス デプロイのみ）、指定されたプロキシを使用するようにターゲット接続が設定されます。
use.proxy.tunneling true これを true に設定し、http.properties でプロキシ構成を指定した場合（オンプレミス デプロイのみ）、指定したトンネルを使用するようにターゲット接続が設定されます。ターゲットが TLS / SSL を使用する場合、このプロパティは無視され、メッセージは常にトンネルを介して送信されます。
enable.method.override false 指定された HTTP メソッドに対して、ターゲット サービスに対する送信リクエストに X-HTTP-Method-Override ヘッダーを設定します。たとえば、<Property name="GET.override.method">POST</Property> のようになります。
*.override.method なし 指定された HTTP メソッドに対して、送信リクエストに X-HTTP-Method-Override ヘッダーを設定します。たとえば、<Property name="GET.override.method">POST</Property> のようになります。
request.streaming.enabled false

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

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

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

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

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

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

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

HTTP コード 400 を唯一の成功コードとして設定すると、HTTP コード 1xx、2xx、3xx は失敗とみなされます。
compression.algorithm なし デフォルトでは、Apigee Edge はクライアント リクエストと同じ圧縮タイプを使用してターゲットにリクエストを転送します。たとえば gzip 圧縮を使用してクライアントからリクエストを受信した場合、Apigee Edge も gzip 圧縮を使用してリクエストをターゲットに転送します。ターゲットから受信したレスポンスで deflate が使用されている場合は、Apigee Edge も deflate を使用してクライアントにレスポンスを転送します。サポートされている値は次のとおりです。
  • gzip: 常に gzip 圧縮を使用してメッセージを送信します
  • deflate: 常に deflate 圧縮を使用してメッセージを送信します
  • none: 常に圧縮なしでメッセージを送信します

https://community.apigee.com/questions/2027/does-apigee-support-compressionde-compression-with.html もご覧ください。
request.retain.headers.
enabled		 true デフォルトでは、Apigee Edge は送信メッセージ上のすべての 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.enabled が false に設定されている場合でも、request.retain.headers プロパティで指定されたヘッダーは送信メッセージに設定されます。
response.retain.headers.
enabled		 true デフォルトでは、Apigee Edge は送信メッセージ上のすべての 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.enabled が false に設定されている場合でも、response.retain.headers プロパティで指定されたヘッダーは送信メッセージに設定されます。
retain.queryparams.
enabled		 true デフォルトでは、Apigee Edge は送信リクエスト上ですべてのクエリ パラメータを常に保持します。true に設定すると、受信リクエストに存在するすべてのクエリ パラメータがターゲット サービスへの送信リクエストに設定されます。
retain.queryparams なし 送信リクエストに設定する特定のクエリ パラメータを定義します。たとえば、リクエスト メッセージのクエリ パラメータ apikey を含めるには、retain.queryparams を apikey に設定します。複数のクエリ パラメータは、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>
    <VirtualHost>default</VirtualHost>
    <VirtualHost>secure</VirtualHost>
  </HTTPProxyConnection>
</ProxyEndpoint>

仮想ホストについて詳しくは、仮想ホストについてをご覧ください。

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

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

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

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

https://community.apigee.com/questions/2027/does-apigee-support-compressionde-compression-with.html もご覧ください。
api.timeout なし

個々の API プロキシにタイムアウトを構成する

ストリーミングが有効にされている API プロキシも含め、指定した時間が経過すると 504 Gateway Timeout ステータスでタイムアウトするように API プロキシを構成できます。これは主に、実行に比較的時間がかかる API プロキシを使用する Private Cloud のお客様向けの機能です。たとえば、3 分でタイムアウトになるプロキシが必要だとします。その場合、api.timeout を次のように使用します。

  1. 最初に、必ずロードバランサ、ルーター、Message Processor が 3 分後にタイムアウトになるように構成してください。
  2. 次に、関連するプロキシが 3 分でタイムアウトになるように構成します。値はミリ秒単位で指定します。例: <Property name="api.timeout">180000</Property>
  3. ただし、システムのタイムアウト値を上げると、パフォーマンスの問題が生じる可能性があるのでご注意ください。これは、api.timeout の設定がないプロキシで、ロードバランサ、ルーター、Message Processor に新しく設定された高いタイムアウト値が使用されるためです。このため、長いタイムアウトを要求しない別の API プロキシで、より短期のタイムアウトが使用されるように構成します。たとえば、次の例の API プロキシは、1 分後にタイムアウトになるように設定されています。
    <Property name="api.timeout">60000</Property>

このプロパティに対して、変数を含める設定はできません。

タイムアウトが標準の Edge Message Processor のタイムアウトである 57 秒より短ければ、Edge のタイムアウトを変更できない Cloud のお客様も、API プロキシを構成できます。

詳しくは、Edge Cloud の io.timeout.millis および api.timeout の設定をご覧ください。

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

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

  1. Router が自身のタイムアウト値を Message Processor に送信します。Router のタイムアウト値は、リクエストを処理する仮想ホストによって設定された proxy_read_timeout の値、またはデフォルトのタイムアウト値である 57 秒になります。
  2. Message Processor では、api.timeout が設定されます。
    1. api.timeout がプロキシレベルで設定されていない場合は、Router のタイムアウトに設定します。
    2. api.timeout がプロキシレベルで設定されている場合は、Message Processor で Router タイムアウトまたは api.timeout の値よりも小さい値に設定します。

  3. api.timeout の値によって、API リクエストからレスポンスまでの API プロキシの最大実行時間が指定されます。

    Message Processor は API プロキシ内で各ポリシーが実行された後、またはターゲット エンドポイントにリクエストを送信する前に、api.timeout の値からリクエスト開始時以降の経過時間を差し引いて残り時間を計算します。算出された値がゼロ未満の場合、リクエストを処理するための最大許容時間が満了しているため、Message Processor によって 504 が返されます。

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

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

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

Node.js アプリケーションの ScriptTarget について

ScriptTarget 要素は、プロキシへの Node.js アプリケーションの統合に使用されます。Node.js と ScriptTarget の使用について詳しくは、以下をご覧ください。

Hosted Targets エンドポイントについて

<HostedTarget/> タグが空の場合は、Edge に対して、Hosted Targets 環境にデプロイされた Node.js アプリケーションをターゲットとして使用するように指示します。詳しくは、Hosted Targets の概要をご覧ください。