第9章 Fuse Online のカスタマイズ

OpenAPI スキーマを Fuse Online にアップロードすると、REST API へのコネクターが利用可能になります。コネクターを選択すると REST API クライアントコネクションを作成できます。その後、新しいインテグレーションを作成し、REST API クライアントコネクションを追加するか、既存のインテグレーションを編集して REST API クライアントコネクションを追加します。

Fuse Online コネクターは OAuth 2.0、HTTP の BASIC 認証、および API キーをサポートします。REST API へのアクセスに TLS (Transport Layer Security) が必要な場合、API は認められた認証局 (CA) が発行する有効な証明書を使用する必要があります。

OAuth を使用する REST API には、クライアントコールバック URL を入力とする承認 URL が必要です。Fuse Online がコネクターを作成した後、コネクターを使用してコネクションを作成する前に、その URL にアクセスして Fuse Online 環境を REST API のクライアントとして登録する必要があります。これにより、Fuse Online 環境による REST API へのアクセスが承認されます。登録の一環として、Fuse Online コールバック URL を提供します。詳細は、Fuse Online のアプリケーションおよびサービスへの接続、Fuse Online を REST API クライアントとして登録 の説明を参照してください。

OAuth を使用する REST API では、Fuse Online は承認の取得に Authorization Code Grant フローのみをサポートします。コネクターを作成するためにアップロードする OpenAPI ドキュメントの securityDefinitions オブジェクトで、flow 属性を accessCode に設定する必要があります。例を以下に示します。

securityDefinitions:
  OauthSecurity:
    type: oauth2
    flow: accessCode
    authorizationUrl: 'https://oauth.simple.api/authorization'
    tokenUrl: 'https://oauth.simple.api/token'

flow を implicit、password、または application に設定しないでください。

REST API クライアントコネクターの OpenAPI スキーマは、循環 (Cyclic) スキーマ参照を持つことができません。たとえば、リクエストまたは応答ボディーを指定する JSON スキーマは、そのスキーマ自体を全体的に参照することはできず、任意数の中間スキーマを介してそれ自体を部分的に参照することもできません。

Fuse Online は、HTTP 2.0 プロトコルをサポートする REST API のコネクターを作成できません。

Fuse Online が REST API クライアントコネクターを作成するとき、OpenAPI ドキュメントの各リソースオペレーションをコネクションアクションにマップします。アクション名とアクションの説明は、OpenAPI ドキュメントのドキュメントから提供されます。

OpenAPI ドキュメントが提供する詳細が多いほど、API への接続時に Fuse Online が提供するサポートも多くなります。たとえば、API 定義はリクエストおよび応答のデータタイプを宣言する必要はありません。タイプ宣言がない場合、Fuse Online は対応するコネクションアクションをタイプレス (タイプがない) として定義します。ただし、インテグレーションでは、タイプレスアクションを実行する API コネクションの直前および直後に、データマッピングステップを追加することはできません。

これに対処するには、OpenAPI ドキュメントにより多くの情報を追加します。API コネクションが実行するアクションにマップする OpenAPI リソースオペレーションを特定します。OpenAPI ドキュメントにて、各オペレーションのリクエストおよび応答タイプを指定する YAML または JSON スキーマがあることを確認します。

スキーマをアップロードした後、OpenAPI ドキュメントをベースとした API 設計のビジュアルエディターである API Designer で、スキーマを確認および編集する機会が与えられます。詳細の追加や更新の保存を行うことができ、Fuse Online は更新に対応する API クライアントコネクターを作成します。Fuse Online がクライアントコネクターを作成した後、OpenAPI ドキュメントを編集できなくなります。変更を実装するには、新しいクライアントコネクターを作成する必要があります。

API の OpenAPI ドキュメントが、application/json コンテンツタイプおよび application/xml コンテンツタイプのサポートを宣言する場合、コネクターは JSON 形式を使用します。OpenAPI ドキュメントが、application/json および application/xml の両方を定義する consumes または produces パラメーターを指定する場合、コネクターは JSON 形式を使用します。

Fuse Online が OAuth2 アプリケーションへアクセスするための承認の取得を試みると、HTTP Basic 認証を使用してクライアントのクレデンシャルを提供します。必要な場合は、このデフォルトの動作を変更し、Fuse Online が HTTP Basic 認証を使用する代わりに、クライアントクレデンシャルをパラメーターとしてプロバイダーに渡すことができます。これは、OAuth アクセストークンの取得に使用される tokenUrl エイドポイントの使用に影響します。

Fuse Online がクライアントクレデンシャルをパラメーターとして渡すよう指定するには、OpenAPI ドキュメントの securityDefinitions セクションで、設定が true の x-authorize-using-parameters ベンダーエクステンションを追加します。以下の例では、最後の行は x-authorize-using-parameters を指定しています。

securityDefinitions:
  concur_oauth2:
    type: 'oauth2'
    flow: 'accessCode'
    authorizationUrl: 'https://example.com/oauth/authorize'
    tokenUrl: 'https://example.com/oauth/token'
    scopes:
      LIST: Access List API
    x-authorize-using-parameters: true

x-authorize-using-parameters ベンダーエクステンションの設定は true または false です。

アクセストークンに有効期限がある場合、そのトークンを使用してアプリケーションに接続する Fuse Online インテグレーションは、トークンの期限が切れると、正常に実行を停止します。新しいアクセストークンを取得するには、アプリケーションに再接続するか、アプリケーションで再登録する必要があります。

必要な場合は、このデフォルトの動作を変更し、Fuse Online が以下の状況で新しいアクセストークンを自動的にリクエストできるようにします。

前述の状況で Fuse Online が新しいアクセストークンを自動的に取得するよう指定するには、OpenAPI ドキュメントの securityDefinitions セクションで x-refresh-token-retry-statuses ベンダーエクステンションを追加します。このエクステンションの設定は、HTTP 応答ステータスコードを指定するコンマ区切りのリストです。アクセストークンの期限が切れたり、Fuse Online が OAuth2 プロバイダーから受信したメッセージにこれらの応答ステータスコードの 1 つがある場合、Fuse Online は自動的に新しいアクセストークンの取得を試みます。以下の例では、最後の行は x-refresh-token-retry-statuses を指定します。

securityDefinitions:
  concur_oauth2:
    type: 'oauth2'
    flow: 'accessCode'
    authorizationUrl: 'https://example.com/oauth/authorize'
    tokenUrl: 'https://example.com/oauth/token'
    scopes:
      LIST: Access List API
    x-refresh-token-retry-statuses: 401,402,403