実装のコード例

XSLT および GatewayScript のコード・スニペットの例を示します。

注記：使用している場合GatewayScript,ゲートウェイの種類に応じて、次のいずれかのコマンドを含める必要があります。
DataPower
Gatewayvar apic = require(./apim.custom.js);
DataPower API
Gatewayvar apic = require('apim');
apic はこのトピック内の GatewayScript の例で使用されている共通名です。 ただし、apic には任意の名前を指定できます。例えば、以下を使用できます。
var apim = require(./apim.custom.js);
そして、apim で呼び出しを開始します。

入力プロパティーへのアクセスのコード・スニペット

以下のコード・ブロックは、XSLT の policyProperties() 関数を使用して入力プロパティーにアクセスする場合の例を示しています。 この例では、a_property という名前のプロパティーを定義しています。このプロパティーは整数値として宣言されますが、XSLT でテキストとして取得されます。
<?xml version="1.0" encoding="UTF-8"?>
<xsl:stylesheet version="1.0"
  xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
  xmlns:dp="http://www.datapower.com/extensions"
  xmlns:func="http://exslt.org/functions"
  xmlns:apim="http://www.ibm.com/apimanagement"
  xmlns:apigw="http://www.ibm.com/xmlns/datapower/2017/11/apigateway"
  exclude-result-prefixes="dp func apim apigw"
  extension-element-prefixes="dp func apim apigw"> 

  <!-- Contains the APIM functions -->
  DataPower
Gateway<xsl:import href="local:///isp/policy/apim.custom.xsl" /> <!-- Use this import for XSLT 1.0.0 only (v5c Gateway) -->
  DataPower API
Gateway<xsl:include href="store:///dp/apim.custom.xsl" /> <!-- Use this include for XSLT 2.0.0 only (API Gateway) -->

  <xsl:template match="/">
    <xsl:variable name="p" select="apim:policyProperties()" />
    <xsl:message>
      The value of my input property is
      <xsl:value-of select="$p/a_property" />
      <apigw:set-variable name="'propfound'" value="'true'"/>
    </xsl:message>
  </xsl:template>

</xsl:stylesheet>
GatewayScript を使用する場合は、以下の関数を呼び出します。
apic.getPolicyProperty(propertyName)
propertyName は、アクセスする入力プロパティーの名前です。 入力プロパティーの名前をブランクになっていると、すべての入力プロパティーが返されます。

ランタイム・コンテキストへのアクセスのコード・スニペット

以下のコード・ブロックは、XSLT の getContext() 関数を使用してランタイム・コンテキストにアクセスする場合の例を示しています。
<?xml version="1.0" encoding="UTF-8"?>
<xsl:stylesheet version="1.0"
  xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
  xmlns:dp="http://www.datapower.com/extensions"
  xmlns:func="http://exslt.org/functions"
  xmlns:apim="http://www.ibm.com/apimanagement"
  exclude-result-prefixes="dp func apim" 
  extension-element-prefixes="dp func apim">

  <!-- Contains the APIM functions -->
  DataPower
Gateway<xsl:import href="local:///isp/policy/apim.custom.xsl" /> <!-- Use this import for XSLT 1.0.0 only (v5c Gateway) -->
  DataPower API
Gateway<xsl:include href="store:///dp/apim.custom.xsl" /> <!-- Use this include for XSLT 2.0.0 only (API Gateway) -->

  <xsl:template match="/">
    <xsl:variable name="client-id" select="apim:getContext('client.app.id')" />
    <xsl:message>
      The calling application is
      <xsl:value-of select="$client-id" />
    </xsl:message>
  </xsl:template>

</xsl:stylesheet>
GatewayScript を使用する場合は、以下の関数を呼び出します。
apic.getContext(varName)
varName は、アクセスするコンテキスト変数の名前です。

コンテキスト変数の完全なリストについては、 API Gateway のコンテキスト変数を参照してください。 DataPower® API Gatewayを使用している場合は、 DataPower API Gateway での GatewayScript ポリシーおよび XSLT ポリシーでのコンテキスト変数の使用も参照してください。

入力ペイロードにアクセスするコード・スニペット

以下のコード・ブロックは、XSLT の payloadRead() 関数を使用して入力ペイロードにアクセスする場合の例を示しています。
<?xml version="1.0" encoding="UTF-8"?>
<xsl:stylesheet version="1.0"
  xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
  xmlns:dp="http://www.datapower.com/extensions"
  xmlns:func="http://exslt.org/functions"
  xmlns:apim="http://www.ibm.com/apimanagement" 
  exclude-result-prefixes="dp func apim"
  extension-element-prefixes="dp func apim">

  <!-- Contains the APIM functions -->
  DataPower
Gateway<xsl:import href="local:///isp/policy/apim.custom.xsl" /> <!-- Use this import for XSLT 1.0.0 only (v5c Gateway) -->
  DataPower API
Gateway<xsl:include href="store:///dp/apim.custom.xsl" /> <!-- Use this include for XSLT 2.0.0 only (API Gateway) -->

  <xsl:template match="/">
    <xsl:variable name="input" select="apim:payloadRead()" />
    <xsl:message>
      The input payload is
      <xsl:copy-of select="$input" />
    </xsl:message>
  </xsl:template>

</xsl:stylesheet>
GatewayScript を使用する場合は、以下の関数を呼び出します。
apic.readInput(callback)
実際に読み取られるペイロードは非同期であるため、コールバックが必要になります。 ペイロードの準備が完了すると、コールバック・メソッドが呼び出されます。
この関数は、要求されたペイロードが含まれている XML ノード・セットを返します。 ペイロードが JSON 形式になっている場合、JSONx ノード・セットが返されます。このノード・セットは、XSLT または GatewayScript のスタイル・シート内で操作することができます。 ペイロードが JSON 形式でも XML 形式でもない場合、返されるノード・セットは空です。
以下の例は、payloadType() 関数を使用して、XSLT の payloadRead() 関数から返されるペイロードのタイプ (XML または JSONx) を判別する方法を示しています。
<?xml version="1.0" encoding="UTF-8"?>
<xsl:stylesheet version="1.0"
  xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
  xmlns:dp="http://www.datapower.com/extensions"
  xmlns:func="http://exslt.org/functions"
  xmlns:apim="http://www.ibm.com/apimanagement"
  exclude-result-prefixes="dp func apim" 
  extension-element-prefixes="dp func apim">

  <!-- Contains the APIM functions -->
  DataPower
Gateway<xsl:import href="local:///isp/policy/apim.custom.xsl" /> <!-- Use this import for XSLT 1.0.0 only (v5c Gateway) -->
  DataPower API
Gateway<xsl:include href="store:///dp/apim.custom.xsl" /> <!-- Use this include for XSLT 2.0.0 only (API Gateway) -->

  <xsl:template match="/">
    <xsl:variable name="payloadType" select="apim:payloadType()" />
    <xsl:message>
      <xsl:text>Payload type is [</xsl:text>
      <xsl:value-of select="$payloadType" />
      <xsl:text>]</xsl:text>
    </xsl:message>
  </xsl:template>

</xsl:stylesheet>

HTTP ヘッダーへのアクセスのコード・スニペット

以下のコード・ブロックは、getContext() 関数を使用して XSLT の HTTP ヘッダーにアクセスする方法の例を示しています。
<?xml version="1.0" encoding="UTF-8"?>
<xsl:stylesheet version="1.0"
  xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
  xmlns:dp="http://www.datapower.com/extensions"
  xmlns:func="http://exslt.org/functions"
  xmlns:apim="http://www.ibm.com/apimanagement" 
  exclude-result-prefixes="dp func apim"
  extension-element-prefixes="dp func apim">

  <!-- Contains the APIM functions -->
  DataPower
Gateway<xsl:import href="local:///isp/policy/apim.custom.xsl" /> <!-- Use this import for XSLT 1.0.0 only (v5c Gateway) -->
  DataPower API
Gateway<xsl:include href="store:///dp/apim.custom.xsl" /> <!-- Use this include for XSLT 2.0.0 only (API Gateway) -->

  <xsl:template match="/">
    <xsl:variable name="content-type" select="apim:getContext('request.headers.content-type')" />
    <xsl:message>
      The request content type is
      <xsl:value-of select="$content-type" />
    </xsl:message>
  </xsl:template>

</xsl:stylesheet>
GatewayScript を使用する場合は、以下の関数を呼び出します。
apic.getContext(request.headers.headerName)
headerName は、アクセスするヘッダーの名前にマップされます。
注： HTTP ヘッダーへのアクセスまたは変更を、 などの拡張機能を使用して行うことは DataPowerdp:set-request-header などの拡張機能を使用して ヘッダーにアクセスしたり変更を加えたりすることは推奨されません。このような操作は、ポリシーが他のポリシーや組み立て手順と組み合わされた場合に予期せぬ結果を招く可能性があるためです。

ペイロードの変更のコード・スニペット

ユーザー定義ポリシー からの出力は、XML ノード・セット (XML または SOAP メッセージを表す)、または JSONx を使用した JSON メッセージでなければなりません。 以下のコード・ブロックは、XSLT でペイロードを変更する方法の例を示しています。 API の ゲートウェイ ・ポリシー・フレームワークが新規または変換されたメッセージを受け入れるのを支援するには、以下の例に示すように、 apim-output テンプレートを呼び出します。
<?xml version="1.0" encoding="UTF-8"?>
<xsl:stylesheet version="1.0"
  xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
  xmlns:apim="http://www.ibm.com/apimanagement"
  xmlns:jsonx="http://www.ibm.com/xmlns/prod/2009/jsonx"
  exclude-result-prefixes="apim"
  extension-element-prefixes="apim">

  <!-- Contains the APIM functions -->
  DataPower
Gateway<xsl:import href="local:///isp/policy/apim.custom.xsl" /> <!-- Use this import for XSLT 1.0.0 only (v5c Gateway) -->
  DataPower API
Gateway<xsl:include href="store:///dp/apim.custom.xsl" /> <!-- Use this include for XSLT 2.0.0 only (API Gateway) -->

  <xsl:template match="/">
    <!-- Creates a JSON document (empty object is for simplicity) -->
    <jsonx:object>
    </jsonx:object>

    <!-- Indicates the media type of the output being produced -->

    <xsl:call-template name="apim:output">
      <xsl:with-param name="mediaType" select="'application/json'" />
    </xsl:call-template>
  </xsl:template>

</xsl:stylesheet>
ここで、mediaType:
  • 出力を JSONx 形式で書き込む場合は 'application/json' です。
  • 出力を XML 形式で書き込む場合は 'application/xml' です。
GatewayScript を使用する場合は、以下の関数を呼び出します。
apic.output(mediaType)
ここで、mediaType は次のとおりです。
  • 出力を JSONx 形式で書き込む場合は application/json です。
  • 出力を XML 形式で書き込む場合は application/xml です。

メディア・タイプを指定することにより、アセンブリー・フローの次のステップが、この新規ペイロードを処理する方法を認識できるようになります。

ヒント: ユーザー定義ポリシー からの出力は、XML または JSONx でなければなりません。 JSONx は、JSON を XML として表現するための IBM 標準形式です。 出力 GatewayScript JSON データを JSONx に変換する方法の 1 つは、同じポリシー・ルールの中で GatewayScript アクションに続けて Convert Query Params to XML アクションを追加することです。 Convert Query Params to XML アクションには、 Default Encoding が JSONに設定された Input Conversion が必要です。 GatewayScript アクションからの出力は、生成される JSONx 用の Convert Query Params to XML アクションに対する入力にする必要があります。

エラー情報の構成のコード・スニペット

以下の XSLT コード・ブロックは、apim-error テンプレートを呼び出して、エラー情報を生成するためのポリシー実装を構成する場合の例を示しています。
<?xml version="1.0" encoding="UTF-8"?>
<xsl:stylesheet version="1.0"
  xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
  xmlns:apim="http://www.ibm.com/apimanagement"
  exclude-result-prefixes="apim"
  extension-element-prefixes="apim">

  <!-- Contains the APIM functions -->
  DataPower
Gateway<xsl:import href="local:///isp/policy/apim.custom.xsl" /> <!-- Use this import for XSLT 1.0.0 only (v5c Gateway) -->
  DataPower API
Gateway<xsl:include href="store:///dp/apim.custom.xsl" /> <!-- Use this include for XSLT 2.0.0 only (API Gateway) -->

  <!-- Indicates this policy has a failure and provides
       additional information for the client application -->
  <xsl:template match="/">
    <xsl:call-template name="apim:error">
      <xsl:with-param name="httpCode" select="'401'" />
      <xsl:with-param name="httpReasonPhrase" select="'Unauthorized'" />
      <xsl:with-param name="errorMessage" select="'Please select a Plan'" />
    </xsl:call-template>
  </xsl:template>

</xsl:stylesheet>
ここで、
  • httpCode は必要なエラー・メッセージのコードです。
  • httpReasonPhrase は、エラーの理由です。
  • errorMessage は、ユーザーの推奨アクションです。
GatewayScript を使用する場合は、以下の関数を呼び出します。
apic.error(name, httpCode, httpReasonPhrase, message)
ここで、
  • name はエラーの名前です。
  • httpCode は必要なエラー・メッセージのコードです。
  • httpReasonPhrase は、エラーの理由です。
  • message は、ユーザーの推奨アクションです。

catch ブロック内のキャッチされた例外へのアクセス

以下の XSLT コード・ブロックは、API アセンブリーの catch ブロックで、現在キャッチされている例外の詳細を取得する方法の一例を示しています。 考えられる使用法としては、キャッチされた例外の詳細を使用してカスタム・エラー応答を作成することなどがあります。

DataPower Gateway (v5互換)の場合：
<?xml version="1.0" encoding="UTF-8"?>
<xsl:stylesheet version="1.0"
  xmlns:xsl="http://www.w3.org/1999/XSL/Transform" 
  xmlns:dp="http://www.datapower.com/extensions" 
  xmlns:apim="http://www.ibm.com/apimanagement" 
  extension-element-prefixes="dp" 
  exclude-result-prefixes="dp apim">

  <xsl:output method="xml" />

  <!-- Contains the APIM functions -->
  <xsl:import href="local:///isp/policy/apim.custom.xsl" /> <!-- Use this import for XSLT 1.0.0 only (v5c Gateway) -->

  <xsl:template match="/">

    <xsl:variable name="exception" select="apim:getError()"/>
    <!-- output desired error message based on the exception -->
    <myError>
       <errorReason><xsl:value-of select="$exception/error/message"/></errorReason>
    </myError>

    <!-- Propagate the HTTP status code and reason phrase from the exception -->       
    <xsl:call-template name="apim:setVariable">
      <xsl:with-param name="varName" select="'message.status.code'"/>
      <xsl:with-param name="value" select="$exception/error/status/code"/>
      <xsl:with-param name="action" select="'Set'" />
    </xsl:call-template>
              
    <xsl:call-template name="apim:setVariable">
      <xsl:with-param name="varName" select="'message.status.reason'"/>
      <xsl:with-param name="value" select="$exception/error/status/reason"/>
      <xsl:with-param name="action" select="'Set'" />
    </xsl:call-template>
       
    </xsl:template>

</xsl:stylesheet>
API Gatewayの場合：
<?xml version="1.0" encoding="UTF-8"?>
<xsl:stylesheet version="1.0"
  xmlns:xsl="http://www.w3.org/1999/XSL/Transform" 
  xmlns:dp="http://www.datapower.com/extensions"
  xmlns:apim="http://www.ibm.com/apimanagement"
  xmlns:apigw="http://www.ibm.com/xmlns/datapower/2017/11/apigateway" 
  extension-element-prefixes="dp apim apigw" 
  exclude-result-prefixes="dp apim apigw">

  <xsl:output method="xml" />

  <!-- Contains the APIM functions -->
  <xsl:include href="store:///dp/apim.custom.xsl" /> <!-- Use this include for XSLT 2.0.0 only (API Gateway) -->

  <xsl:template match="/">

    <xsl:variable name="exception" select="apigw:get-error()"/>
    <!-- output desired error message based on the exception -->
    <myError>
       <errorReason><xsl:value-of select="$exception/error/message"/></errorReason>
    </myError>

    <!-- Propagate the HTTP status code and reason phrase from the exception -->       
    <xsl:call-template name="apim:setVariable">
      <xsl:with-param name="varName" select="'message.status.code'"/>
      <xsl:with-param name="value" select="$exception/error/status/code"/>
      <xsl:with-param name="action" select="'Set'" />
    </xsl:call-template>
              
    <xsl:call-template name="apim:setVariable">
      <xsl:with-param name="varName" select="'message.status.reason'"/>
      <xsl:with-param name="value" select="$exception/error/status/reason"/>
      <xsl:with-param name="action" select="'Set'" />
    </xsl:call-template>
       
    </xsl:template>

</xsl:stylesheet>
apim:getError() 関数および apigw:get-error() 関数は、XML ノード・セットを返します。以下に例を示します。
<?xml version="1.0" encoding="UTF-8"?>
<error>
    <name>RuntimeError</name>
    <message>This is a thrown Runtime Error</message>
    <policyTitle>Throw Runtime Error</policyTitle>
    <status>
        <code>500</code>
        <reason>Internal Server Error</reason>
    </status>
</error>
GatewayScript を使用する場合は、以下の関数を呼び出します。
apim.getError()
これは JSON オブジェクトを返します。例:
{
  "name": "OperationError",
  "message": "This is a thrown Operation Error",
  "policyTitle": "Throw Operation Error",
  "status": {
    "code": "500",
    "reason": "Internal Server Error"
  }
}

変数の設定のコード・スニペット

以下の XSLT コード・ブロックは、setVariable テンプレートを呼び出して、ランタイム変数を指定のストリング値に設定する場合の例を示しています。
<?xml version="1.0" encoding="UTF-8"?>
<xsl:stylesheet version="1.0"
  xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
  xmlns:dp="http://www.datapower.com/extensions"
  xmlns:func="http://exslt.org/functions"
  xmlns:apim="http://www.ibm.com/apimanagement" 
  exclude-result-prefixes="dp func apim"
  extension-element-prefixes="dp func apim">

  <!-- Contains the APIM functions -->
  DataPower
Gateway<xsl:import href="local:///isp/policy/apim.custom.xsl" /> <!-- Use this import for XSLT 1.0.0 only (v5c Gateway) -->
  DataPower API
Gateway<xsl:include href="store:///dp/apim.custom.xsl" /> <!-- Use this include for XSLT 2.0.0 only (API Gateway) -->

  <xsl:template match="/">
    <xsl:variable name="" select="'https://endpoint.host.com/data'" />
    <xsl:call-template name="apim:setVariable">
      <xsl:with-param name="varName" select="'serviceEndpoint'" />
      <xsl:with-param name="value" select="$targetUrl" />
      <xsl:with-param name="action" select="'set'" />
    </xsl:call-template>
    <xsl:message>
      <xsl:text>Variable [</xsl:text>
      <xsl:value-of select="'serviceEndpoint'" />
      <xsl:text>] = [</xsl:text>
      <xsl:value-of select="$targetUrl" />
      <xsl:text>]</xsl:text>
    </xsl:message>
    <dp:url-open target="{$targetUrl}" response="xml" http-method="get"/>
    </xsl:message>
  </xsl:template>

</xsl:stylesheet>
ここで、
  • varName は、値を設定するランタイム変数の名前です。
  • value は、設定する変数のストリング値です。 リテラル値や、別の変数でも構いません。 例えば、指定した変数を要求内の Content-Type ヘッダーの値に設定するには、value を $(request.headers.content-type) として指定します。
GatewayScript を使用する場合は、以下の関数を呼び出します。
apic.setvariable(varName, varValue, action)
ここで、
  • varName は、値を設定するランタイム変数の名前、追加するランタイム変数の名前、またはクリアするランタイム変数の名前です。
  • varValue は、設定する変数のストリング値です。 リテラル値や、別の変数でも構いません。 例えば、指定した変数を要求内の Content-Type ヘッダーの値に設定するには、varValue を request.headers.content-type として指定します。 このプロパティーが必要となるのは、set または add がアクションとして指定されている場合のみです。
  • action は変数に適用するアクションです。 有効なオプション:
    • set
    • add
    • clear
    オプションを設定しなかった場合は、デフォルト・オプションの set が適用されます。
以下の XSLT は、getVariable() 関数を使用してランタイム変数の値を取得する場合の例を示しています。
<?xml version="1.0" encoding="UTF-8"?>
<xsl:stylesheet version="1.0"
  xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
  xmlns:dp="http://www.datapower.com/extensions"
  xmlns:func="http://exslt.org/functions"
  xmlns:apim="http://www.ibm.com/apimanagement" 
  exclude-result-prefixes="dp func apim"
  extension-element-prefixes="dp func apim">

  <!-- Contains the APIM functions -->
  DataPower
Gateway<xsl:import href="local:///isp/policy/apim.custom.xsl" /> <!-- Use this import for XSLT 1.0.0 only (v5c Gateway) -->
  DataPower API
Gateway<xsl:include href="store:///dp/apim.custom.xsl" /> <!-- Use this include for XSLT 2.0.0 only (API Gateway) -->

  <xsl:template match="/">
    <xsl:variable name="varValue" select="apim:getVariable('serviceEndpoint')" />
    <xsl:message>
      <xsl:text>Variable [</xsl:text>
      <xsl:value-of select="'serviceEndpoint'" />
      <xsl:text>] = [</xsl:text>
      <xsl:value-of select="$varValue" />
      <xsl:text>]</xsl:text>
    </xsl:message>
    <dp:url-open target="{$varValue}" response="xml" http-method="get"/>
  </xsl:template>

</xsl:stylesheet>
ここで
  • varValue は、値を取得するランタイム変数の名前です。
GatewayScript を使用する場合は、以下の関数を呼び出します。
apic.getvariable(varName)
varName は、値を取得する対象となるランタイム変数の名前です。