OpenAPI 仕様に対する IBM 拡張

オンラインで編集する

OpenAPI 定義ファイル内の x-ibm-configuration オブジェクトを使用して、 IBM® API Connectに固有の拡張機能を追加します。

x-ibm-configuration 拡張の構造は以下のとおりです。

x-ibm-configuration:
  enforced: enforced_boolean
  forceHttp500ForSoap11: forceHttp500ForSoap11_boolean
  compile-json-schemas: compile_json_schemas_boolean
  enforce-form-data-parameter: enforce_form_data_parameter_boolean
  phase: Phase
  testable: test_boolean
  cors:
    enabled: cors_boolean
  buffering: buffering_boolean
  activity-log:
      activity_logging_extension
  assembly:
    execute:
      - assembly_component
  gateway: gateway_type
  type: api_type
  properties:
      properties_extension
  catalogs:
      catalogs_extension

以下の表に、 API Connectで使用されるさまざまな拡張機能、それらが必要かどうか、それらの使用と動作の説明、およびそれらのタイプをリストします。

表 1. IBM 拡張機能
拡張子 必須 説明 タイプ
phase いいえ API の成熟度を記述するために使用します。 この拡張には次の値を指定できます。
  • identified: API は初期の概念的なフェーズにあり、設計も実装も完了していません。
  • specified: API は、設計が完了して内部のマイルストーンを通過しましたが、まだ実装されていません。
  • realized: API は実装フェーズにあります。
 ストリング
testable いいえ この testable 拡張機能を使用して、 Consumer Catalog のテストツールで API をテストできるかどうかを指定します。 ブール値
enforced いいえ enforced 拡張を使用して、API を強制するために API Connect ゲートウェイを使用するかどうかを指定します。
  • true は、API を強制するために API Connect ゲートウェイが使用されることを示します。
  • false は、API を強制するために API Connect ゲートウェイが使用されないことを示します。
 ブール値
cors いいえ CORS アクセス制御を API で使用するかどうかを指定するには、この cors 拡張機能を使用します。 この拡張には、ブール型の enabled フィールドが含まれています。 オブジェクト (ブール型フィールドを 1 つ含む)
DataPower API Gateway onlyactivity-log いいえ 分析に保管されている API アクティビティー用にロギングの設定を構成するには、activity-log 拡張を使用します。 ユーザーが指定する設定は、API アクティビティーの詳細の収集および保管に関するデフォルトの設定値をオーバーライドします。 オブジェクト
assembly いいえ assembly 拡張を使用して、ポリシーおよびロジックの API への適用を記述します。 この拡張には、ポリシーを適用順に並べた配列を含んだ execute フィールドが含まれています。 この拡張に、catch されるエラー・ケースの配列を含んだ catch フィールドを含めることができます。

execute フィールドの使用については、 executeを参照してください。

この catch フィールドの使用方法については、 「catch」 を参照してください。

 オブジェクト
gateway いいえ gateway 拡張を使用して、使用するゲートウェイのタイプを指定します。 DataPower® Gateway (v5 compatible) または DataPower API Gatewayを使用している場合は、以下のいずれかの値を指定する必要があります。
  • datapower-gateway (DataPower Gateway (v5 compatible))
  • datapower-api-gateway (DataPower API Gateway)

ゲートウェイの種類については、 「ゲートウェイ API Connect の種類」 を参照してください。

 ストリング
type いいえ type 拡張には、次の値を指定します。
  • rest
  • wsdl
properties いいえ properties 拡張を使用して、API で使用するプロパティーを定義します。 オブジェクト（ プロパティ ）
catalogs いいえ properties 拡張内で定義されたプロパティーに対してカタログ固有の値を定義するには catalogs 拡張を使用します。 オブジェクト（ カタログ ）
DataPower API Gateway onlyforceHttp500ForSoap11 いいえ forceHttp500ForSoap11 拡張を使用して、SOAP 1.1 API でエラーが発生したときに 500 レスポンスコードを強制します。 このプロパティは、APAR IT46043 を含む DataPower フィックスパックでのみ動作します。 ブール値
compile-json-schemas いいえ この拡張機能を使用すると、設定のデプロイ時にJSONスキーマの事前コンパイルを有効にできます。 true に設定すると、新しい設定が適用される際に JSON スキーマがコンパイルされ、キャッシュされます。これにより、最初のメッセージが処理される時点でコンパイルが完了し、利用可能な状態になります。 ブール値
buffering いいえ この拡張機能を使用して、処理の前にAPIリクエストとレスポンスをバッファリングするかどうかを制御します。 これにより、 DataPower message-buffering コマンドが有効になります
  • true: 処理の前に、APIのリクエストとレスポンスをバッファリングします。 APIのリクエストとレスポンスは、バイナリ大容量オブジェクト（BLOB）として読み込まれます。
  • false: 処理の前にAPIのリクエストやレスポンスをバッファリングしないでください。 APIのリクエストとレスポンスはストリーム形式で送信されます。 ストリーム化されたデータを読み取れるのは、非同期API呼び出しのみです。 メッセージ処理においてペイロードレベルのデータ解析が必要な場合、データを取得するためにバッファリングが行われます。 この設定はデフォルト値です。
 ブール値
enforce-form-data-parameter いいえ このコマンドは、APIルーティング中にフォームデータパラメータを解決して設定するかどうかを指定します。
  • この設定を有効にし、APIパスの処理によってフォームデータが構成される場合、ルーティング中にペイロードをBLOBデータとして解析し、対応するフィールドにコンテキスト変数として設定します。
  • この機能が有効になっておらず、かつ必須のフォームデータパラメータが指定されていない場合、処理はBLOBとして解決されず、パラメータに値が設定されません。
 ブール値

次の例は、 API Connectによって強制され、実現済み状態であり、 Consumer Catalog 内のテストツールを通じてテスト可能で、 CORS によるアクセス制御が有効化されており、 URL を呼び出した後、リクエストまたはレスポンスからフィールドをマスキングする単純なアセンブリを持つAPI x-ibm-extension のセクションを示しています。

x-ibm-configuration:
  enforced: true
  phase: realized
  testable: true
  cors:
    enabled: true
  assembly:
    execute:
      - invoke:
          title: Example Invoke
          target-url: 'https://example.com/api'
          description: Example description
      - redact:
        actions:
          - action: redact
            from: 
              - request
              - response
            path: //*[@name='secondaryAddress']/*[@name='streetAddress']
  properties:
    ID:
      value: 1234
      description: An ID to be used for validating.
      encoded: false
  catalogs:
    Sandbox:
      properties:
        ID: 5678