REST ノードでのローカル環境変数の使用

REST 要求ノードは、ノード・プロパティーに設定された値を動的に変更するために使用できる、いくつかのローカル環境メッセージ・ツリー変数をサポートします。

以下の表は、 LocalEnvironment.Destination.REST.Request メッセージ・ツリー内のエレメントを示しています。これらのエレメントを使用して、 RESTRequest ノードおよび RESTAsyncRequest ノードのプロパティーをオーバーライドすることができます。 ローカル環境変数によって設定されるすべてのプロパティーは、 RESTRequest ノードと RESTAsyncRequest ノードの両方に適用されます。

この表には、ESQL を使用して値を設定する方法の例が含まれていますが、 Mapping ノードなどの変換ノードを使用して値を設定することもできます。 Mapping ノードから LocalEnvironment にアクセスするには、 メッセージ・アセンブリー・コンポーネントを組み込むためのメッセージ・マップのカスタマイズを参照してください。
表 1. 入力ローカル環境プロパティー
エレメント名 タイプ 説明
操作 ストリング この値は、REST API で呼び出す操作の名前です。 この環境変数は、ノードの Operation プロパティーを指定変更します。 例:
SET OutputLocalEnvironment.Destination.REST.Request.Operation = 'updateCustomerByID';
パラメーター。parameter_name ストリング 操作のパラメーターに使用する値を指定します。 LocalEnvironment で指定された値は、ノードの Parameters テーブルで指定されたリテラル値や XPath/ESQL 式を上書きします。 例:
SET OutputLocalEnvironment.Destination.REST.Request.Parameters.max = 10;
SET OutputLocalEnvironment.Destination.REST.Request.Parameters.filter = 'Fred Bloggs';
注: 値が XPath/ESQL 式の場合、値はストリング・リテラルとしてリモート REST API に渡されます (XPath/ESQL 式としては評価されません)。

REST パラメーターを定義し、それらの値をメッセージ・マップに設定するには、Add User Defined 関数を使用して parameter_name エレメントを追加してから、その値を設定するためのマッピングを提供します。 詳しくは、 「ユーザー定義の追加」機能を使用したローカル環境ツリーの「変数」フォルダーの構成を参照してください。

配列パラメーターを指定するには、パラメーターを複数回定義する。 例えば、値'a'、'b'、'c'を持つlistと呼ばれる配列プロパティは次のように定義できる：

SET OutputLocalEnvironment.Destination.REST.Request.Parameters.list[1] = 'a';
SET OutputLocalEnvironment.Destination.REST.Request.Parameters.list[2] = 'b';
SET OutputLocalEnvironment.Destination.REST.Request.Parameters.list[3] = 'c';
オブジェクト・パラメータを指定するには、要素の子としてオブジェクト・プロパティとその値を指定します。 例えば、オブジェクト・パラメーターがパラメーターを複数回呼び出したとする。 例えば、値red = 100、green = 200、blue = 300を持つcolorと呼ばれる配列プロパティは、次のように定義できる：

SET OutputLocalEnvironment.Destination.REST.Request.Parameters.colour.red = 100;
SET OutputLocalEnvironment.Destination.REST.Request.Parameters.colour.green = 200;
SET OutputLocalEnvironment.Destination.REST.Request.Parameters.colour.blue = 300;
ContentType ストリング この値は、要求で REST API に送信する Content-Type ヘッダーの値です。 この環境変数は、ノードの Content-Type プロパティーを指定変更します。 例:
SET OutputLocalEnvironment.Destination.REST.Request.ContentType = 'application/vnd.ibm-demo+json';
Accept ストリング この値は、要求で REST API に送信する Accept ヘッダーの値です。 この環境変数は、ノードの Accept プロパティーを指定変更します。 例:
SET OutputLocalEnvironment.Destination.REST.Request.Accept = 'application/json';
SecurityIdentity ストリング 値は、 mqsicredentials、 ibmint set credential、または mqsisetdbparms コマンドで定義されているセキュリティ ID の名前でなければならない。 「rest::」接頭部は含めないでください。 この環境変数はノードの Security identity プロパティをオーバーライドする。 例:
SET OutputLocalEnvironment.Destination.REST.Request.SecurityIdentity = 'myApiKey';
UserID ストリング この環境変数を指定すると、ノードの LocalEnvironment.Destination.REST.Request.SecurityIdentity オーバーライドおよび Security identity プロパティーによって指定されたすべての値がオーバーライドされます。

LocalEnvironment.Destination.REST.Request.UserID 環境変数を指定する場合、LocalEnvironment.Destination.REST.Request.Password 環境変数も必要です。
パスワード ストリング この環境変数を指定すると、ノードの LocalEnvironment.Destination.REST.Request.SecurityIdentity オーバーライドおよび Security identity プロパティーによって指定されたすべての値がオーバーライドされます。

LocalEnvironment.Destination.REST.Request.Password 環境変数を指定する場合、LocalEnvironment.Destination.REST.Request.UserID 環境変数も必要です。
APIKey ストリング この環境変数を指定すると、ノードの LocalEnvironment.Destination.REST.Request.SecurityIdentity オーバーライドおよび Security identity プロパティーによって指定されたすべての値がオーバーライドされます。

LocalEnvironment.Destination.REST.Request.APIKey 環境変数は単独で指定することも、LocalEnvironment.Destination.REST.Request.UserID 環境変数および LocalEnvironment.Destination.REST.Request.Password 環境変数と組み合わせて指定することもできます。
BearerToken ストリング

この環境変数が指定されると、 LocalEnvironment.Destination.REST.Request.SecurityIdentity オーバーライドとノードの Security identity プロパティで指定されているすべての値がオーバーライドされます。

環境変数 LocalEnvironment.Destination.REST.Request.BearerToken は、単独で指定することも、環境変数 LocalEnvironment.Destination.REST.Request.BearerToken と組み合わせて指定することもできる。
タイムアウト integer REST API が操作を処理するのをノードが待つ時間 (秒)。 この環境変数は、ノードの Request timeout (sec) プロパティーを指定変更します。 例:
SET OutputLocalEnvironment.Destination.REST.Request.Timeout = 300;
BaseURL ストリング この環境変数は、ノードの Base URL override プロパティー、および REST API の定義を含む Swagger 文書で指定されたベース URL を指定変更します。 例:
SET OutputLocalEnvironment.Destination.REST.Request.BaseURL = 'https://my-prod-server.ibm.com/customerdb/v1';
ProxyURL ストリング この環境変数は、ノードの HTTP(S) proxy location プロパティーを指定変更します。 例:
SET OutputLocalEnvironment.Destination.REST.Request.ProxyURL = 'http://my-proxy-server.ibm.com';
FollowRedirection ブール値 この環境変数は、ノードの Follow HTTP(S) redirection プロパティーを指定変更します。 例:
SET OutputLocalEnvironment.Destination.REST.Request.FollowRedirection = TRUE;
KeepAlive ブール値 この環境変数は、ノードの Enable HTTP 1/1 keep-alive プロパティーを指定変更します。 例:
SET OutputLocalEnvironment.Destination.REST.Request.KeepAlive = FALSE;
Compression ストリング この環境変数は、ノードの Compression プロパティーを指定変更します。 有効値は、以下のとおりです。
  • gzip
  • zlib-圧縮
  • raw-deflate (ロー・デフラグ)
例:
SET OutputLocalEnvironment.Destination.REST.Request.Compression = 'zlib-deflate';
プロトコル ストリング この環境変数は、ノードの Protocol プロパティーを指定変更します。 有効値は、以下のとおりです。
  • TLS
  • TLSv1
  • TLSv1.2
  • TLSv1.3
  • SSL_TLS
  • SSL_TLSv2
例:
SET OutputLocalEnvironment.Destination.REST.Request.Protocol = 'TLSv1.2';
AllowedCiphers ストリング この環境変数は、ノードの Allowed SSL Ciphers プロパティーを指定変更します。 例:
SET OutputLocalEnvironment.Destination.REST.Request.AllowedCiphers = 'SSL_RSA_FIPS_WITH_3DES_EDE_CBC_SHA';
HostnameChecking ブール値 この環境変数は、ノードの Enable SSL certificate hostname checking プロパティーを指定変更します。 例:
SET OutputLocalEnvironment.Destination.REST.Request.HostnameChecking = FALSE;
KeyAlias ストリング この環境変数は、ノードの SSL client authentication key alias プロパティーを指定変更します。 例:
SET OutputLocalEnvironment.Destination.REST.Request.KeyAlias = 'myClientCertificate';
EnableCRLCheck ブール値 この環境変数は、ノードの Enable certificate revocation list checking プロパティーを指定変更します。 例:
SET OutputLocalEnvironment.Destination.REST.Request.EnableCRLCheck = TRUE;
AcceptCompressedResponses ストリング この環境変数は、ノードの Accept compressed responses by default プロパティーを指定変更します。 例:
SET OutputLocalEnvironment.Destination.REST.Request.AcceptCompressedResponses = TRUE;
ServicePrincipalName ストリング 統合ノードが Kerberos セキュリティー・プロトコルと折衝する際に使用するサービス・プリンシパル名 (SPN) を指定します。 例:
SET OutputLocalEnvironment.Destination.REST.Request.ServicePrincipalName = 'HTTP/iib.iibservice2.com:7800';
セキュリティスキーム。セキュリティスキーム.セキュリティアイデンティティ ストリング 指定のセキュリティー・スキーマに使用するセキュリティー ID の名前を指定します。 指定したセキュリティー ID は、指定したセキュリティー・スキーマに対してのみ使用されます。

この環境変数を指定すると、ノードの LocalEnvironment.Destination.REST.Request.SecurityIdentity オーバーライドおよび Security identity プロパティーが指定変更されます。

セキュリティー・スキーマの名前は、REST API の定義を含む Swagger 文書内のセキュリティー定義オブジェクトのセキュリティー・スキーマ・オブジェクトの名前に対応します。

値は、 mqsicredentials、 ibmint set credential、または mqsisetdbparms コマンドで定義されたセキュリティ ID の名前でなければならない。 「rest::」接頭部は含めないでください。 例:

SET OutputLocalEnvironment.Destination.REST.Request.SecuritySchemes.petstore_auth.SecurityIdentity = 'myIdentity3'
セキュリティスキーム。セキュリティスキーム。ユーザーID ストリング HTTP 基本認証使用時に指定のセキュリティー・スキーマに使用するユーザー ID を指定します。 指定したユーザー ID は、指定したセキュリティー・スキーマに対してのみ使用されます。

この環境変数を指定すると、LocalEnvironment.Destination.REST.Request.SecuritySchemes.security_scheme.SecurityIdentity または LocalEnvironment.Destination.REST.Request.SecurityIdentity のいずれかのオーバーライドを使用して、セキュリティー ID で指定されたユーザー ID がオーバーライドされます。また、ノードの Security identity プロパティーもオーバーライドされます。

セキュリティー・スキーマの名前は、REST API の定義を含む Swagger 文書内のセキュリティー定義オブジェクトのセキュリティー・スキーマ・オブジェクトの名前に対応します。 例:
SET OutputLocalEnvironment.Destination.REST.Request.SecuritySchemes.security_scheme.UserID='bob'
SecuritySchemes.security_scheme。パスワード ストリング HTTP 基本認証使用時に指定のセキュリティー・スキーマに使用するパスワードを指定します。 指定したパスワードは、指定したセキュリティー・スキーマに対してのみ使用されます。

この環境変数が指定されると、 LocalEnvironment.Destination.REST.Request.SecuritySchemes.security_scheme.SecurityIdentity または LocalEnvironment.Destination.REST.Request.SecurityIdentity オーバーライドを使用してセキュリティ ID で指定されたパスワードがオーバーライドされ、ノードの Security identity プロパティもオーバーライドされます。

セキュリティー・スキーマの名前は、REST API の定義を含む Swagger 文書内のセキュリティー定義オブジェクトのセキュリティー・スキーマ・オブジェクトの名前に対応します。 例:
SET OutputLocalEnvironment.Destination.REST.Request.SecuritySchemes.petstore_auth.Password='myPassword'
SecuritySchemes.security_scheme。API キー ストリング HTTP 基本認証使用時に指定のセキュリティー・スキーマに使用する API キーを指定します。 指定した API キーは、指定したセキュリティー・スキーマに対してのみ使用されます。

この環境変数が指定されると、 LocalEnvironment.Destination.REST.Request.SecuritySchemes.security_scheme.SecurityIdentity または LocalEnvironment.Destination.REST.Request.SecurityIdentity オーバーライドを使用してセキュリティ ID で指定された API キーがオーバーライドされ、ノードの Security identity プロパティもオーバーライドされます。

セキュリティー・スキーマの名前は、REST API の定義を含む Swagger 文書内のセキュリティー定義オブジェクトのセキュリティー・スキーマ・オブジェクトの名前に対応します。 例:
SET OutputLocalEnvironment.Destination.REST.Request.SecuritySchemes.petstore_auth.APIKey='438438920909329039032'
SecuritySchemes.security_scheme.BearerToken ストリング

HTTP ベアラ認証を使用する場合に、指定したセキュリティ・スキームで使用するベアラ・トークンを指定します。 指定されたベアラ・トークンは、指定されたセキュリティ・スキームでのみ使用されます。

この環境変数を指定すると、 LocalEnvironment.Destination.REST.Request.SecuritySchemes.security_scheme.SecurityIdentity または LocalEnvironment.Destination.REST.Request.SecurityIdentity オーバーライドを使用してセキュリティ ID で指定されたベアラ・トークンがオーバーライドされ、ノードのセキュリティ ID プロパティもオーバーライドされます。

セキュリティスキームの名前は、REST API の定義を含む openapi ドキュメントの Security Definitions オブジェクトの Security Scheme オブジェクトの名前に対応します。 例:
SET OutputLocalEnvironment.Destination.REST.Request.SecuritySchemes.petstore_auth.BearerToken='token123'
UserContext 混合内容 RESTAsyncRequest ノードによって保管されるコンテキスト・データを指定します。 一致する要求については、後で RESTAsyncResponse ノードによってデータにアクセスできます。

ユーザー・コンテキストを使用して、 RESTAsyncRequest ノードから RESTAsyncResponse ノードに渡されるデータを指定できます。 ユーザー・コンテキスト・データを保管するには、 RESTAsyncRequest ノードの前に、 OutputLocalEnvironment.Destination.REST.Request.UserContext 環境変数に値を設定するか、その下に子ノードを作成してデータを取り込みます。

例えば、ESQL 式を使用して値を設定するには、次のようにします。
SET OutputLocalEnvironment.Destination.REST.Request.UserContext = 'Some important information';
SET OutputLocalEnvironment.Destination.REST.Request.UserContext.Name.FirstName = 'Fred';
SET OutputLocalEnvironment.Destination.REST.Request.UserContext.Name.Surname = 'Bloggs';
SET OutputLocalEnvironment.Destination.REST.Request.UserContext.MyData.Binary = CAST('A piece of data' AS BLOB CCSID 1208);

Mapping ノードを使用して、混合した子エレメント OutputLocalEnvironment.Destination.REST.Request.UserContext.mixedにマップすることにより、値を設定できます。 Mapping ノードを使用してサブエレメントを作成するには、ユーザー定義エレメントを使用するか、 xsd:any をキャストしてサブエレメントにマップします。 詳しくは、 RESTAsyncRequest ノードを参照。

RESTAsyncResponse ノードの後にユーザー・コンテキスト・データにアクセスするには、 LocalEnvironment.REST.Response.UserContext 環境変数の値または子を読み取ります。
QueryStringDoNotPercentEncodeCharacters ストリング URI の作成中にパーセントでエンコードされない、照会ストリング内の文字を指定します。
例えば、コンマ記号と「より大」記号がパーセントでエンコードされないように指定するには、次のようにします。
SET OutputLocalEnvironment.Destination.REST.Request.QueryStringDoNotPercentEncodeCharacters = ',>';

パーセントでエンコードされない文字のデフォルト・セットは、アスタリスク (*)、マイナス (-)、ピリオド (.)、および下線 (_) です。
以下の表は、出力メッセージの伝搬時に RESTRequest ノードによって LocalEnvironment に書き込まれるデータを示しています。
表 2. RESTRequest ノードによって生成される出力ローカル環境プロパティー
エレメント タイプ 説明
LocalEnvironment.WrittenDestination.REST.Method ストリング REST API の操作を呼び出すときに使用される HTTP メソッド。
LocalEnvironment.WrittenDestination.REST.URL ストリング REST API の操作を呼び出すときに使用される URL。
LocalEnvironment.WrittenDestination.REST.RequestHeadersSize integer REST API に送信される要求ヘッダーのサイズ。
LocalEnvironment.WrittenDestination.REST.RequestBodySize integer REST APIに送信されるリクエストボディのサイズ。
LocalEnvironment.WrittenDestination.REST.StatusCode integer REST API からの応答の HTTP 状況コード。
LocalEnvironment.WrittenDestination.REST.ResponseHeadersSize integer REST API から受信される応答ヘッダーのサイズ。
LocalEnvironment.WrittenDestination.REST.ResponseBodySize integer REST API から受信される応答本体のサイズ。
LocalEnvironment.WrittenDestination.REST.TotalRequestTime integer REST API の操作を呼び出す際の合計経過時間。
LocalEnvironment.WrittenDestination.REST.ResponseCode ストリング

HTTP ステータスコード、または OpenAPI ドキュメント内の呼び出された操作の応答セクションで定義されているステータスコード範囲。 ステータスコードが期待される応答コードのリストにない場合、文字列としてのステータスコードは以下のようになる：

たとえば、応答セクションがステータスコード200、および 2XX をリストしている場合、 StatusCode が200の応答は ResponseCode が200になるが、 StatusCode 204の応答は ResponseCode が 2XX になり、 StatusCode が300の応答は ResponseCode が300になる。
LocalEnvironment.WrittenDestination.REST.ResponseCodeExpected ブール値

レスポンスに対する HTTP ステータスコードが、 OpenAPI ドキュメントでその操作に対して定義されている、期待されるレスポンスコードのリストに含まれていれば真。

たとえば、レスポンスセクションにステータスコード200と 2XX がリストされている場合、 StatusCode が200または204のレスポンスは ResponseCodeExpected がTRUEになるが、 StatusCode が300のレスポンスは ResponseCodeExpected がFALSEになる。
以下の表は、出力メッセージの伝搬時に RESTAsyncRequest ノードによって書き込まれるデータを示しています。
表 3. RESTAsyncRequest ノードによって生成される出力ローカル環境プロパティー:
エレメント タイプ 説明
LocalEnvironment.WrittenDestination.REST.Method ストリング REST API の操作を呼び出すときに使用される HTTP メソッド。
LocalEnvironment.WrittenDestination.REST.URL ストリング REST API の操作を呼び出すときに使用される URL。
LocalEnvironment.WrittenDestination.REST.RequestHeadersSize integer REST API に送信される要求ヘッダーのサイズ。
LocalEnvironment.WrittenDestination.REST.RequestBodySize integer REST APIに送信されるリクエストボディのサイズ。
LocalEnvironment.WrittenDestination.REST.CorrelationID blob RESTAsyncRequest と RESTAsyncResponse ノードの間で要求と応答を相関させるために使用される相関 ID。
以下の表は、出力メッセージの伝搬時に RESTAsyncResponse ノードによって書き込まれるデータを示しています。
表 4。 RESTAsyncResponse ノードによって生成される出力ローカル環境プロパティー:
エレメント タイプ 説明
LocalEnvironment.REST.Response.CorrelationID blob RESTAsyncRequest ノードと RESTAsyncResponse ノードの間の要求と応答の関連付けに使用される相関 ID。
LocalEnvironment.REST.Response.StatusCode integer REST API からの応答の HTTP 状況コード。
LocalEnvironment.REST.Response.ResponseHeadersSize integer REST API から受信される応答ヘッダーのサイズ。
LocalEnvironment.REST.Response.ResponseBodySize integer REST API から受信される応答本体のサイズ。
LocalEnvironment.REST.Response.UserContext 混合内容 OutputLocalEnvironment.Destination.REST.Request.UserContext に保管された情報は、応答スレッドによって取り出すことができます。
LocalEnvironment.REST.Response.ResponseCode ストリング

HTTP ステータスコード、または OpenAPI ドキュメント内の呼び出された操作の応答セクションで定義されているステータスコード範囲。 ステータスコードが期待される応答コードのリストにない場合、文字列としてのステータスコードは以下のようになる：

たとえば、応答セクションがステータスコード200、および 2XX をリストしている場合、 StatusCode が200の応答は ResponseCode が200になるが、 StatusCode 204の応答は ResponseCode が 2XX になり、 StatusCode が300の応答は ResponseCode が300になる。
LocalEnvironment.REST.Response.ResponseCodeExpected ブール値

レスポンスに対する HTTP ステータスコードが、 OpenAPI ドキュメントでその操作に対して定義されている、期待されるレスポンスコードのリストに含まれていれば真。

たとえば、レスポンスセクションにステータスコード200と 2XX がリストされている場合、 StatusCode が200または204のレスポンスは ResponseCodeExpected がTRUEになるが、 StatusCode が300のレスポンスは ResponseCodeExpected がFALSEになる。