API Connect コンテキスト変数

アセンブリー操作でデフォルト・パラメーター値を定義するとき、またはポリシーを定義するときに getContext() 関数を使用するときに参照できる IBM® API Connect コンテキスト変数のリスト。

以下の表を示します。

アセンブリー・コンポーネントの実装について詳しくは、 OpenAPI 2.0 API アセンブリーへのエレメントの組み込み、 OpenAPI 2.0 API アセンブリーへのエレメントの組み込みを参照してください。 また、 API Connect でコンテキスト変数を参照する方法については、 API Connect および GatewayScript でのコンテキスト変数の使用および DataPower API Gatewayを参照してください。

ユーザー定義ポリシーの作成について詳しくは、 ポリシーのオーサリングを参照してください。

一般的なコンテキスト変数

注:
  • plan 変数 (plan.name や plan.version) の場合、要求された操作が ID を必要としており、クライアントが認証チェックに合格した場合にのみ、プランの情報が利用可能です。
  • API を DataPower® Gateway (v5 compatible) にデプロイする場合、クライアント ID とクライアント秘密鍵を除き、フォーム入力をパラメーターとして API に渡すことはサポートされません。 この制限は、API を DataPower API Gatewayにデプロイする場合には適用されません。
表 1. API Connect コンテキスト変数
名前 説明 許可
DataPower API Gateway onlyapi.catalog.id API が公開されているカタログの ID。 読み取り/書き込み
DataPower API Gateway onlyapi.catalog.name API が公開されているカタログの名前。 読み取り/書き込み
DataPower API Gateway onlyapi.catalog.path このカタログを表すパス・セグメント。 読み取り/書き込み
api.endpoint.address API ゲートウェイ・エンドポイントのアドレス。 読み取り/書き込み
api.endpoint.hostname アプリケーションによって要求された API ゲートウェイ・エンドポイントのホスト名。 読み取り/書き込み
DataPower API Gateway onlyapi.id API の ID。 読み取り/書き込み
api.name API の名前。これは、API の OpenAPI 定義の x-ibm-name フィールドに対応します。 読み取り/書き込み
api.operation.id 操作の ID。 読み取り/書き込み
api.operation.path 操作のパス。 読み取り/書き込み
api.org.id API プロバイダーの組織 ID。 読み取り/書き込み
api.org.name API プロバイダーの組織のショート・ネーム。 読み取り/書き込み
api.properties.propertyname カスタム API プロパティーの名前。 プロパティーの値はカタログ固有です。
注:
  • カスタム・プロパティーへの書き込み権限があるのは、ユーザー・インターフェースを使用している場合のみであり、GatewayScript を使用している場合は権限はありません。
 読み取り/書き込み
api.root API 基本パス。 読み取り/書き込み
api.type API のタイプ (REST または SOAP)。 読み取り/書き込み
api.version API のバージョン・ストリング。 読み取り/書き込み
client.app.id 要求で受け取ったクライアント ID またはアプリケーション・キー。 読み取り/書き込み
DataPower API Gateway onlyclient.app.'lifecycle-state' 呼び出し元クライアント・アプリケーションのライフサイクル状況。 考えられる値は以下のとおりです。
  • DEVELOPMENT
  • PRODUCTION (デフォルト)
 読み取り/書き込み
DataPower API Gateway onlyclient.app.metadata.key アプリケーション・メタデータ・キーのストリング値 (key はキーの名前)。

メタデータ・キーは、 apic apps:create コマンドまたは apic apps:update コマンドを使用してアプリケーションに追加できます。メタデータ・キーは、コマンドに渡される構成ファイル・パラメーターに含めます。

例：
apic apps:create myapp.yaml --server myserver.com 
--org myorg --catalog mycatalog --consumer-org mycorg
ここで、myapp.yaml には以下が含まれます。
name: myapp
title: My test application
metadata:
  key1: value1
  key2: value2
  key3: value3
  key4: value4
  key5: value5
その後、以下のようなコンテキスト変数を使用して、API アセンブリー・ポリシー内のメタデータ・キーの値を取得できます。
client.app.metadata.key3

アプリケーション・メタデータを追加すると、ゲートウェイ・トランザクションのパフォーマンスに影響する可能性があることに注意してください。

 読み取り/書き込み
client.app.name 要求発行元として認識されたアプリケーションの名前。 読み取り/書き込み
client.app.secret 要求内で受け取ったクライアント・シークレット。 読み取り/書き込み
client.app.type 要求を発行したクライアント・アプリケーションのタイプ。 読み取り/書き込み
client.org.id このアプリケーションを所有している組織の固有の識別キー。 読み取り/書き込み
client.org.name このアプリケーションを所有している組織の名前。 読み取り/書き込み
DataPower API Gateway onlyclient.result クライアント・セキュリティー・ポリシーの結果。SUCCESS または FAILURE。 読み取り/書き込み
DataPower API Gateway onlyclient.third_party.type 抽出されたクライアント資格情報の第三者認証に使用されたユーザー・レジストリー。 考えられる値は LDAP および auth-url です。 読み取り/書き込み
DataPower API Gateway onlyclient.third_party.headers 第三者認証中に API 認証 URL に送信された要求に追加されるヘッダーの配列。 読み取り/書き込み
DataPower API Gateway onlyclient.third_party.response.authenticated 第三者認証の結果。 考えられる値は以下のとおりです。
  • true: 認証は正常に終了しました。
  • false: 認証に失敗しました。
 読み取り/書き込み
DataPower API Gateway onlyclient.third_party.response.user 第三者認証のユーザー。 読み取り/書き込み
DataPower API Gateway onlyclient.title 要求内で受け取った資格情報のタイトル。 読み取り/書き込み
DataPower Gateway (Classic) onlyenv.name API が公開されているカタログの名前。 読み取り/書き込み
DataPower Gateway (Classic) onlyenv.path このカタログを表すパス・セグメント。 読み取り/書き込み
DataPower API Gateway onlyerror.message エラーのメッセージ・テキスト。 読み取り/書き込み
DataPower API Gateway onlyerror.name エラーの名前。 読み取り専用
DataPower API Gateway onlylog アセンブリー・ログ・アクションで収集されるトランザクション・データ。 読み取り/書き込み
message.attachments 複数パーツ・メッセージ内の添付ファイルの配列。 読み取り/書き込み
message.attachments[].body 複数パーツ・メッセージ内の添付ファイル・ペイロード。 読み取り/書き込み
message.attachments[].headers 複数パーツ・メッセージ内の添付ファイル・ヘッダー。 読み取り/書き込み
message.body 要求メッセージまたは応答メッセージのペイロード。
注: message.body コンテキスト変数は、 getContext() 関数ではサポートされません。 代わりに、getvariable() 関数を使用します。
 読み取り/書き込み
message.headers.name メッセージの現在の名前付きヘッダーの値、または複数パーツ・メッセージのルート・パートの現在の名前付きヘッダーの値。

name セグメントは大/小文字を区別しません。

 読み取り/書き込み
DataPower API Gateway onlymessage.original.headers.name HTTP メッセージの元の名前付きヘッダーの値。 アセンブリーに呼び出しアクションが含まれている場合、この値は、呼び出された URL からの応答メッセージの元の名前付きヘッダーによって自動的に取り込まれます。

name セグメントは大/小文字を区別しません。

 読み取り専用
DataPower API Gateway onlymessage.package.headers.name 複数パーツ・メッセージの現在の名前付きヘッダーの値。

name セグメントは大/小文字を区別しません。

 読み取り/書き込み
message.status.code 応答の HTTP 状況コード。 読み取り/書き込み
message.status.reason 応答の HTTP 理由フレーズ。 読み取り/書き込み
DataPower API Gateway onlymessage.variables.name メッセージ内のプロパティーの値。 例えば、myvarがメッセージ内のプロパティーである場合、message.variables.myvarを読み取ることによって、myvarプロパティーの値を取得できます。 読み取り/書き込み
plan.name プランの名前。 読み取り/書き込み
plan.id プランの固有 ID。 読み取り/書き込み
plan.rate-limit プランのレート制限。時間間隔あたりの API 呼び出しの数です。 読み取り/書き込み
DataPower API Gateway onlyplan.rate-limit[index].hard-limit [index]によって識別されるレート制限のスキームのハード制限設定。 読み取り/書き込み
DataPower API Gateway onlyplan.rate-limit[index].value [index]によって、識別されるレート制限のスキームの値。 この構文はrate/intervalです。 読み取り/書き込み
plan.spaceId プランが含まれているスペースの固有 ID。 読み取り/書き込み
plan.spaceName プランが含まれているスペースの名前。 読み取り/書き込み
plan.version プランのバージョン番号。 読み取り/書き込み
request.authorization 構文解析されたHTTPauthorizationのヘッダー。 読み取り専用
request.body 着信要求のペイロード。 読み取り専用
request.content-type 正規化されたコンテンツ・タイプの値。 読み取り専用
request.date ゲートウェイが要求をおおよそいつ受信したかを示す日付オブジェクト。 読み取り専用
request.headers.name HTTP 要求の元の名前付きヘッダーの値、または複数パーツ要求のルート・パートの現在の名前付きヘッダーの値。

name セグメントは大/小文字を区別しません。

要求ヘッダーは、プリフロー・ポリシーでのみ変更できます。 詳しくは、 プリフロー・ポリシーのカスタマイズを参照してください。

 読み取り/書き込み
DataPower API Gateway onlyrequest.original.headers.name HTTP 要求の元の名前付きヘッダーの値。 この変数が作成されるのは、要求ヘッダーが変更された場合だけです。

name セグメントは大/小文字を区別しません。

 読み取り専用
DataPower API Gateway onlyrequest.package.headers.name 複数パーツ要求の名前付きヘッダーの値。

name セグメントは大/小文字を区別しません。

 読み取り専用
DataPower API Gateway onlyrequest.parameters 着信パラメーターは、パス・パラメーターと照会パラメーターから取得できます。  
DataPower API Gateway onlyrequest.parameters.name.locations name で指定されるパラメーターと関連付けられるパラメーター・タイプを指定するストリングの配列。 パラメーター・タイプとしてサポートされているキーワードは、以下のとおりです。
formData
パラメーターはフォーム・データとして本文内にあります。
header
パラメーターは要求ヘッダー内にあります。
path
パラメーターはパス内にあります。
query
パラメーターは照会内にあります。
 読み取り専用
DataPower API Gateway onlyrequest.parameters.name.values name で指定されるパラメーターと関連付けられるパラメーター・タイプの値を含む配列。 例えば、最初の値が path in request.parameters.myparam.locations[]の場合、 request.parameters.myparam.values[] の最初の値は、 myparamに関連付けられたパス値の配列です。

要求パラメーターは、プリフロー・ポリシーでのみ変更できます。 詳しくは、 プリフロー・ポリシーのカスタマイズを参照してください。

 読み取り/書き込み
DataPower API Gateway onlyrequest.original.parameters.name.values name に指定されたパラメーターと関連付けられている パラメーター・タイプの元の値が含まれた配列。 この変数が作成されるのは、 要求パラメーター値が変更された場合だけです。 読み取り専用
request.path API の基本パスで始まる request.uri のパス・セクション。基本パスを開始する「/」文字が含まれます。 読み取り専用
DataPower API Gateway onlyrequest.protocol 要求の受信に使用されるプロトコル:httpまたはhttps。 読み取り専用
request.querystring 先頭に疑問符 (?) が指定されていない要求照会ストリング。 読み取り専用
request.search 先頭に疑問符 (?) が指定されている要求照会ストリング。 読み取り専用
request.uri アプリケーションからの完全な HTTP 要求の URI。 読み取り専用
request.verb この要求の HTTP 動詞。 読み取り専用
DataPower API Gateway onlysession.apiGateway 要求を受け取るゲートウェイ。 読み取り専用
DataPower API Gateway onlysession.apiGatewayName API Manager で定義されている API ゲートウェイの名前。 読み取り専用
DataPower API Gateway onlysession.clientAddress 要求を送信したクライアントのアドレス。 読み取り専用
DataPower API Gateway onlysession.domainName ゲートウェイが属するドメインの名前。 読み取り専用
DataPower API Gateway onlysession.globalTransactionID ログ内のグローバル・トランザクション ID。 読み取り専用
DataPower API Gateway onlysession.localAddress DataPower® Gateway 上のゲートウェイのアドレス。 読み取り専用
DataPower API Gateway onlysession.timeStarted ゲートウェイが要求の処理を開始した時刻。 読み取り専用
DataPower API Gateway onlysession.transactionID ゲートウェイ要求のトランザクション ID。 読み取り専用
system.datetime ゲートウェイのシステムのタイム・ゾーンにおける現在の日時を表すストリングを返します。 読み取り専用
system.time

ゲートウェイのシステムのタイム・ゾーンにおける現在の時刻を表すストリングを返します。

 読み取り専用
system.time.hour ゲートウェイのシステムのタイム・ゾーンにおける現在の時刻の「時間」を表す 0 から 23 までの数値を返します。 読み取り専用
system.time.minute ゲートウェイのシステムのタイム・ゾーンにおける現在の時刻の「分」を表す 0 から 59 までの数値を返します。 読み取り専用
system.time.seconds ゲートウェイのシステムのタイム・ゾーンにおける現在の時刻の「秒」を表す 0 から 59 までの数値を返します。 読み取り専用
system.date

ゲートウェイのシステムのタイム・ゾーンにおける現在の日付を表すストリングを返します。

 読み取り専用
system.date.day-of-week ゲートウェイのシステムのタイム・ゾーンにおける曜日を表す 1 から 7 (月曜から日曜) までの数値を返します。 読み取り専用
system.date.day-of-month ゲートウェイのシステムのタイム・ゾーンにおける日を表す 1 から 31 までの数値を返します。 読み取り専用
system.date.month ゲートウェイのシステムのタイム・ゾーンにおける月を表す 1 から 12 までの数値を返します。 読み取り専用
system.date.year ゲートウェイのシステムのタイム・ゾーンにおける年を表す 4 桁の数値を返します。 読み取り専用
system.timezone ゲートウェイのシステムのタイム・ゾーンの ISO 8601 の ID を返します。この ID には、記号、2 桁の時間、および分が含まれる場合があります。 例えば、-04:00 などです。 読み取り専用

OAuth コンテキスト変数- DataPower Gateway (v5 compatible)

このセクションで説明する OAuth コンテキスト変数は、 DataPower Gateway (v5 compatible)にのみ適用されます。 DataPower API Gatewayに適用される OAuth コンテキスト変数について詳しくは、 OAuth コンテキスト変数を参照してください。

表 2. OAuth コンテキスト変数 (DataPower Gateway (v5 compatible))。
注: ほとんどの OAuth コンテキスト変数は、 IBM API Connect が OAuth リソース・サーバーとして機能している場合にのみ使用可能です。 ただし、oauth.introspect 変数は、サード・パーティー・プロバイダーとの統合時にも使用可能です。
名前 説明
oauth.access-token 要求が OAuth で認証される場合、この変数にはアクセス・トークン・ストリングが含まれます。
oauth.miscinfo この変数には、認証 URL およびメタデータ URL のヘッダーに明示的に含まれる情報が格納されます。

詳細は URL を参照してください。
oauth.not-after 要求が OAuth で認証される場合、この変数にはトークンの有効期限が切れる日付が含まれます。
oauth.not-before 要求が OAuth で認証される場合、この変数にはトークンの発行日付が含まれます。
oauth.resource-owner 要求が OAuth で認証される場合、この変数にはリソース所有者の名前が含まれます。
oauth.scope 要求が OAuth で認証される場合、この変数には、このアクセス・トークンのスコープが含まれます。
oauth.introspect.active 常にイントロスペクションで使用可能です。 ブール値です。
oauth.introspect.response 常にイントロスペクションで使用可能です。 現在の完全な応答ペイロードを示します。 ペイロード値の例を以下に示します。 {“active”:true, “client_id”, “xxx-xxx”, “token_type”, “bearer”, “scope”:“neon”}
他の変数を oauth.introspect.<variable> という形式でサード・パーティーから利用できる場合があります。 上記のペイロード例をデコードすると、さらなる処理に以下の変数を使用できるようになります。
oauth.introspect.client_id: xxx-xxx 
oauth.introspect.token_type: bearer
oauth.introspect.scope: neon

アプリケーション証明書のコンテキスト変数

以下の表では、API へのアクセスを検証するために証明書が使用されるときに使用可能なコンテキスト変数について説明します。ただし、これらのコンテキスト変数は、使用されている署名メカニズムによって異なります。詳しくは、 インターネット X.509 Public Key Infrastructure Certificate and CRL Profile specificationを参照してください。

表 3. アプリケーション証明書のコンテキスト変数
名前 説明
application.certificate.Base64 Base64 形式
application.certificate.fingerprint フィンガープリント
application.certificate.Version バージョン
application.certificate.SerialNumber シリアル番号
application.certificate.SignatureAlgorithm 署名アルゴリズム
application.certificate.Issuer 証明書の発行者
application.certificate.Subject 件名
application.certificate.NotBefore この日付より前は無効
application.certificate.NotAfter この日付より後は無効
application.certificate.SubjectPublicKeyAlgorithm サブジェクト公開鍵のアルゴリズム
application.certificate.SubjectPublicKeyBitLength サブジェクト公開鍵の長さ
application.certificate.KeyValue.type アルゴリズムとキーに依存するさまざまなコンテキスト変数。 例えば、以下のようなコンテキスト変数です。
  • application.certificate.KeyValue.RSAKeyValue.Modulus
  • application.certificate.KeyValue.RSAKeyValue.Exponent

API アクティビティー・ロギング・コンテキスト変数

API のアクティビティー・ロギングが有効になっていると、log コンテキスト変数が作成されます。log コンテキスト変数には、API 実行イベントに関連するデータが含まれます。 API の実行が完了すると、log コンテキスト変数が API イベント・レコードに書き込まれ、このレコードが API 分析による以降のアクセスのために保管されます。 log コンテキスト変数に含まれるフィールドについて詳しくは、 API イベント・レコードのフィールドを参照してください。

アクティビティー・ロギングを有効にして構成する方法は、以下のように、使用するゲートウェイのタイプによって異なります。
アクティビティー・ロギング構成により、log コンテキスト変数のデフォルト・コンテンツが定義されますが、API アセンブリー内でこれを変更できます。以下に例を示します。

GraphQL コンテキスト変数

API 処理およびアセンブリー・アクションから生成された GraphQL 照会/応答変数は、API コンテキストの message.attributes.graphql コンテキスト変数に保管されます。

表 4。 GraphQL コンテキスト変数
名前 説明
message.attributes.graphql GraphQL メッセージの照会属性と応答属性。
message.attributes.graphql.query GraphQL 照会の属性 (照会ストリング、操作名、変数など)。
message.attributes.graphql.query.query GraphQL 照会ストリング。
message.attributes.graphql.query.variables GraphQL 変数のマップ。
message.attributes.graphql.query.operationName 実行する操作の名前。
message.attributes.graphql.query.operationType 実行する操作のタイプ。
message.attributes.graphql.request GraphQL 要求の属性。
message.attributes.graphql.request.fieldCost 照会でアクセスされたすべてのフィールドのコストの重みづけされた合計。 各フィールド・アクセスのコストは、スキーマで構成されます。 このカウントには、フィールド・コストが 0.0 に設定されていないフィールドが含まれます。
message.attributes.graphql.request.fieldCounts 指定した照会によって各フィールドを取得できる最大回数。 この数値は、フィールドの値を生成するリゾルバーを実行する必要がある回数と同じです。 このカウントには、フィールド・コストが 0.0 に設定されていないフィールドが含まれます。
message.attributes.graphql.request.typeCost 照会で取得されたすべてのタイプのコストの重みづけされた合計。 各タイプのコストは、スキーマで構成されます。 このカウントには、タイプ・コストが 0.0 に設定されていないタイプが含まれます。
message.attributes.graphql.request.typeCounts 指定した照会によって各タイプの値を取得できる最大回数。 このカウントには、タイプ・コストが 0.0 に設定されていないタイプが含まれます。
message.attributes.graphql.response.fieldCost 照会に対する応答内のすべてのフィールドのコストの重みづけされた合計。 各フィールド・アクセスのコストは、スキーマで構成されます。 要求内の分析構成に基づいてこの合計を計算できない場合、フィールド・コストは割り当て可能な最大整数値として表されます。
message.attributes.graphql.response.fieldCounts 照会に対する応答内で各フィールドが取得された回数。 この数値は、フィールドの値を生成するリゾルバーを実行する必要がある回数と同じです。 要求内の分析構成に基づいてこの合計を計算できない場合、フィールド・カウントは割り当て可能な最大整数値として表されます。
message.attributes.graphql.response.typeCost 照会に対する応答内のすべてのタイプのコストの重みづけされた合計。 各タイプのコストは、スキーマで構成されます。 要求内の分析構成に基づいてこの合計を計算できない場合、タイプ・コストは割り当て可能な最大整数値として表されます。
message.attributes.graphql.response.typeCounts 照会に対する応答に各タイプの値が含まれていた回数。 要求内の分析構成に基づいてこの合計を計算できない場合、タイプ・カウントは割り当て可能な最大整数値として表されます。
message.attributes.parse.GraphQLIntrospection アセンブリー GraphQL イントロスペクト・アクションのイントロスペクション・タイプ。 GraphQL 照会が解析されると、このコンテキスト変数には以下のいずれかの値が設定されます。
  • not-introspection
  • custom-introspection
  • default-introspection