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

このトピックでは、トランスポート プロパティについて説明します。トランスポート プロパティは、メッセージングと接続の動作を制御するために 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 を唯一の成功コードとして設定すると、コード 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.enabledfalse に設定されている場合、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.enabledfalse に設定されている場合、response.retain.headers プロパティで指定されているヘッダーのすべてが送信メッセージでも設定されます。
retain.queryparams.
enabled
true デフォルトでは、Apigee Edge は送信リクエスト上ですべてのクエリ パラメータを常に保持します。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>
        <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 のタイムアウトを変更できない Cloud のお客様も、標準の Edge Message Processor のタイムアウト値である 57 秒より短ければ、API プロキシ タイムアウトを構成できます。

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

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

Edge for the Cloud では、io.timeout.millisapi.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 の概要をご覧ください。