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

このページの内容は Apigee と Apigee ハイブリッドに該当します。

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

このトピックでは、トランスポート プロパティについて説明します。トランスポート プロパティは、TargetEndpoint 構成と ProxyEndpoint 構成で設定でき、メッセージングと接続の動作を制御します。TargetEndpoint と ProxyEndpoint の構成オプションの詳細については、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.post.without.content.length	false	本文にコンテンツのない POST リクエストを送信できます。
allow.put.without.content.length	false	本文にコンテンツのない PUT リクエストを送信できます。
allow.tls.session.resumption	true	true（デフォルト）の場合、クライアントはターゲットに新たに接続するときに TLS セッションを再利用します。TLS セッションを再利用しない場合は false に設定します。一般的に、セッションの再利用をすることで接続時間が短くなりますが、一部のターゲットではセッションの再利用がサポートされていないか、簡単ではない場合があります。
keepalive.timeout.millis	60000	接続プール内のターゲット接続の接続アイドル タイムアウト。プール内の接続が指定した上限時間を超えてアイドル状態にあると、その接続は閉じられます。
connect.timeout.millis	3,000	ターゲット接続のタイムアウト。接続タイムアウトが発生すると、Apigee により HTTP 503 ステータス コードが返されます。ターゲット サーバーの定義で LoadBalancer が使用され、タイムアウトが発生すると、HTTP 504 ステータス コードが返される場合があります。 注: 場合によっては、Apigee が接続を最大 3 回自動的に再試行します。その結果、合計再試行時間が connect.timeout.millis に構成されている時間を超える場合があります。
ignore.allow.header.for.405	true	405 ステータス コードをクライアントに返すことができます。フラグを有効にすると、Apigee により 502 ではなく 405 のステータス コードが返されます。
io.timeout.millis	55000	指定したミリ秒間に読み取るデータが存在しない場合、または指定したミリ秒間にソケットでデータ書き込みの準備ができていない場合に、トランザクションはタイムアウトとして処理されます。 Ingress から HTTP リクエストの読み取り中にタイムアウトが発生した場合、408 Request Timeout が返されます。ターゲットへのリクエストの書き込み中にタイムアウトが発生した場合、408 Request Timeout は返されません。 HTTP リクエストの書き込み中または HTTP レスポンスの読み取り中にタイムアウトが発生した場合、504 Gateway Timeout が返されます。 注: WebSocket 接続を使用している場合、このプロパティを使ってデフォルト値である 5,500 を超える値に設定されているタイムアウトは、WebSocket 接続がアイドル状態のときには適用されません。接続は 55 秒後に終了します。 io.timeout.millis および api.timeout の設定をご覧ください。
supports.http11	true	これが true のときにクライアントが 1.1 のリクエストを送信すると、ターゲットにも 1.1 のリクエストが送信されます。それ以外の場合は 1.0 のリクエストがターゲットに送信されます。
use.proxy	true	API プロキシの転送プロキシを構成するで説明されているとおり、Apigee ハイブリッド オーバーライド ファイルに HTTP_PROXY 構成が含まれている場合は、このプロパティを使用して、どのプロキシがそのプロキシ構成を使用しないようにするかについて、管理と制御を行うことができます。 false に設定すると、API プロキシでは、プロキシで設定されたターゲット接続に対して、Apigee ハイブリッド オーバーライド ファイルで指定された HTTP プロキシ構成がスキップされます。
use.proxy.tunneling	true	これを 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 コード 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 では受信したメッセージに設定された圧縮タイプ（gzip、deflate、なし）が使用されます。たとえば gzip 圧縮を使用してクライアントからリクエストを受信した場合、Apigee でも gzip 圧縮を使用してリクエストがターゲットに転送されます。ターゲットから受信したレスポンスで deflate が使用されている場合は、Apigee でも deflate を使用してクライアントにレスポンスが転送されます。サポートされている値は次のとおりです。 gzip: 常に gzip 圧縮を使用してメッセージを送信します deflate: 常に deflate 圧縮を使用してメッセージを送信します none: 常に圧縮なしでメッセージを送信します Apigee は、GZIP / DEFLATE 圧縮を使用した圧縮と解凍もサポートしていますかをご覧ください。
request.retain.headers. enabled	true	デフォルトでは、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.enabled が false に設定されている場合でも、request.retain.headers プロパティで指定されたヘッダーは送信メッセージに設定されます。
response.retain.headers. enabled	true	デフォルトでは、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.enabled が false に設定されている場合でも、response.retain.headers プロパティで指定されたヘッダーは送信メッセージに設定されます。
retain.queryparams. enabled	true	デフォルトでは、Apigee では送信リクエスト上のすべてのクエリ パラメータが常に保持されます。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>
  </HTTPProxyConnection>
</ProxyEndpoint>

リクエスト ヘッダー

受信した HTTP リクエストには、クライアントから送信された HTTP ヘッダーが含まれています。名前が X-Apigee-* パターンに一致するヘッダーは、クライアントが送信した受信リクエストから削除されます。この名前のパターンは Apigee で予約されています。

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 プロキシを構成できます。 重要: 指定するタイムアウトは、標準の Message Processor のタイムアウトである 300 秒より短くする必要があります。 たとえば、180,000 ミリ秒（3 分）後にタイムアウトするようにプロキシを構成するには、次のプロパティを HTTPProxyConnection に追加します。 <Property name="api.timeout">180000</Property> このプロパティを変数で設定することはできません。 io.timeout.millis および api.timeout の設定をご覧ください。
HTTPHeader.allowDuplicates	なし	特定のヘッダーに対する重複したヘッダーを許可する場合は、この設定を使用します。 <HTTPProxyConnection> <Properties> <Property name="HTTPHeader.allowDuplicates">Content-Type,Authorization</Property> </Properties> </HTTPProxyConnection>
HTTPHeader.multiValued	なし	特定のヘッダーに対する重複したヘッダーを許可する場合は、この設定を使用します。 <HTTPProxyConnection> <Properties> <Property name="HTTPHeader.multiValued">Content-Type,Authorization</Property> </Properties> </HTTPProxyConnection>

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

io.timeout.millis と api.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 リクエストの書き込み中または HTTP レスポンスの読み取り中にタイムアウトが発生した場合、504 Gateway Timeout が返されます。