変換

オンラインで編集

IBM® Verify で Webhook を適用すると、リモート・システムに接続することになります。リモート・システムは、テナント管理者によって作成およびデプロイされているとは限りません。これらのリモート・システムは柔軟性のない API を公開する可能性があるため、Verify とリモート・システムの間の機能的な統合を実現するために、Webhook 呼び出しの要求ペイロードまたは応答ペイロードの変更が必要になる場合があります。

この統合を実現するため、Webhook は変換と呼ばれる機能を公開します。管理者はこの機能を使用して、HTTP 要求と応答を変更する式を作成できます。

Webhook 変換は CEL 式であり、その出力は、既知のキーを含むマップです。これらのキーは、HTTP 要求または応答を構成する部分にマップされます。変換出力の各キーはオプションであり、指定しない場合、要求または応答のその部分は変更されません。

発信変換

発信変換は、Webhook 宛先に送信される前に HTTP 要求に適用されます。

以下の表に、発信変換の入力引数を示します。

名前	タイプ	読み取り専用	注
`body`	`map[string]object`	N
`header`	`map[string]list[string]`	N
`method`	`string`	N
`path`	`string`	N
`host`	`string`	Y	構成されているすべての URL でホストが整合している場合にのみ表示されます。

これらのパラメーターは、CEL 仕様に従って参照できます。

CEL 式は、次の例に示すように、事前割り当てキーを使用して宣言されるマップです。

{
  "body":body,
  "header":header,
  "path":path   
}

注: 変更を加えない場合は、キーを含める必要はありません。上記の例は、マップ形式を示すためのものです。

以下の表に、発信変換キーを示します。

名前	タイプ	注
`body`	`map[string]object` または `string`
`header`	`map[string]list[string]` または `map[string]string`
`method`	`string`
`path`	`string`
`query`	`map[string]string` または `map[string]list[string]`
`skip_authentication`	`boolean`	true に設定すると、構成済み認証メカニズムは使用されません。このキーは、変換によって許可の詳細が要求に追加される場合に使用します。
`title_case_bearer`	`boolean`	この変換は、受信APIがヘッダーを正しく処理するために大文字小文字の区切りが必要な場合に使用する。 `true` に設定されると、 `authorization` ヘッダーのauthorization-type指定子 `bearer` が存在する場合、タイトルケース(`bearer` -> `Bearer`)を使用するように変換される。

着信変換

着信変換は、開始された Webhook から受信した HTTP 応答に適用されます。

以下の表に、着信変換の入力引数を示します。

名前	タイプ	読み取り専用	注
`body`	`map[string]object`	N
`header`	`map[string]list[string]`	Y
`status_code`	`integer`	Y
`request`	`map[string]object`	Y	発信変換引数が入っています。例えば、 `request.body` と入力すると、元の要求本文にアクセスします。

注:

変更できるのは、着信変換の body のみです。 header または status_code を変更しても効果はありません。
着信変換は、状況コードが検証された後でのみ開始されます。 Webhook またはリソースの expectedStatus フィールドが適切に設定されていることを確認してください。

変換における一般的なバグ

同様の一般的な問題が発生する可能性があります。

数値の等式の失敗

HTTP 本体から取得した数値に対して比較を実行すると、数値に対する等号検査が予期したとおりに機能しない場合があります。以下のコードは、ペイロード、ペイロードに適用された CEL、および出力の例です。

body argument
value

{
  "value": 2
}

CEL:

{ 
  "body" : body.put("gte": body.value >= 2)
}

Result:

{
  "value":2,
  "gte": false
}

この結果は、body.value 式が 10 進値を生成しているためです。 JSON として、数値は定義により整数ではありません。キャストによって動作が修正されます。以下の例を参照してください。

Incoming body:

{
  "value": 2
}

CEL:

{
   "body" : body.put("gte": int(body.value) >= 2)
}

Result:

{
  "value":2,
  "gte": true
}

要求からの本体の削除

一部の API では、すべての情報を URL とヘッダーで送信し、リクエストにボディを含めないことが必要になる場合があります。これらの API では、リクエストから送信される HTTPを削除するための変換が必要になる場合があります。発信要求から本文を削除するには、以下のアクションを実行します。

content-type を空ストリングに設定してください。
HTTPを空文字列に設定します。

以下の例は、発信変換の一部として本体を削除する方法を示しています。

CEL:

{
  "body":"",
  "header": header.put("content-type","")
}