Menu Close

第4章 Fuse Online のパブリック REST API エンドポイントの呼び出し方法

OCP で Fuse Online を稼働している場合、各 Fuse Online 環境でパブリック REST API エンドポイントを公開できます。継続的インテグレーション/継続的デリバリー (CI/CD) の外部ツールにより、これらのエンドポイントを呼び出して、Fuse Online 環境のリソースを操作することができます。

外部ツールでこれらのエンドポイントを呼び出しできるようにするには、先に各 Fuse Online 環境で、OpenShift 管理者が Fuse Online のパブリック REST API エンドポイントを公開する必要があります。API エンドポイントを呼び出すコマンドで、エンドポイントが動作する Fuse Online 環境の URL、シークレットトークン、および承認トークンを指定します。

詳細は以下のトピックを参照してください。

4.1. 外部ツールによって使用される Fuse Online パブリック REST API の公開

オンサイトで OCP に Fuse Online を実行している場合、外部ツールを使用して Fuse Online 環境から別の Fuse Online 環境に Fuse Online インテグレーションをコピーすることがあります。外部 CI/CD ツールは、Jenkins ジョブ、Ansible Playbook、cron ベースのシェルスクリプトなどです。たとえば、Ansible Playbook ではインテグレーションを Fuse Online 開発環境からエクスポートし、Fuse Online テスト環境にインポートすることができます。

これを有効にするには、各 Fuse Online 環境の Fuse Online パブリック REST API エンドポイントを公開する必要があります。つまり、Fuse Online がインストールされている OpenShift プロジェクトごとに、ここの手順を繰り返す必要があります。

前提条件

  • Fuse Online がインストールされている OCP プロジェクトが必要です。
  • oc クライアントツールがインストール済みであり、Fuse Online がインストールされている OCP クラスターに接続されている必要があります。
  • 外部 CI/CD ツールを使用しており、マーク付けされたインテグレーションを Fuse Online 環境から別の Fuse Online 環境にコピーする状況です。
  • syndesis-operator grant コマンドの実行には、クラスターの管理者権限が必要です。クラスターの管理者権限はなく、OpenShift プロジェクトの管理者権限があるユーザーは、他のコマンドを実行できます。

手順

  1. クラスターの管理者権限を持つアカウントで OpenShift にログインします。以下に例を示します。

    oc login -u admin -p admin

    クラスターの管理者権限は、syndesis-operator grant コマンドにのみ必要ですが、クラスター管理者がすべての手順を実行することを想定します。

  2. Fuse Online が稼働している OpenShift プロジェクトに切り替えます。このプロジェクトでのみパブリック API を公開します。以下に例を示します。

    oc project fuse-online-north

  3. ロールを syndesis-public-oauthproxy サービスアカウントに付与します。OpenShift プロジェクトでは、このサービスアカウントを使用して OAuth プロキシーサービスを実行します。クラスターの管理権限を持つユーザーアカウントを指定します。以下に例を示します。

    syndesis-operator grant --user developer

    このコマンドは、クラスターロールとクラスターのロールバインディングを作成し、これを syndesis-public-oauthproxy サービスアカウントに割り当てます。ClusterRoleBinding は、API を公開する OpenShift プロジェクトの名前を指定します。この例では、名前は fuse-online-north になります。

    • ClusterRole: syndesis-auth-delegator
    • ClusterRoleBinding: syndesis-fuse-online-north-auth-delegator
  4. クライアントサービスアカウントを作成し、Fuse Online のパブリック API にアクセスする権限を付与します。

    1. 選択した名前で OpenShift サービスアカウントを作成します。たとえば、次のコマンドを実行すると cicd-client サービスアカウントが作成されます。

      oc create serviceaccount cicd-client

      パブリック API エンドポイントを呼び出すコマンドは、このアカウントを使用してパブリック API にアクセスします。また、このサービスアカウントは、API エンドポイントへの呼び出しで指定する必要のあるシークレットトークンを取得するために必要です。この説明は「パブリック REST API エンドポイントを呼び出すためのシークレットトークンの取得」を参照してください。

    2. Fuse Online のパブリック API にアクセスするための権限をクライアントサービスアカウントに付与します。Fuse Online がインストールされた OpenShift プロジェクトの名前が fuse-online-north で、API サービスにアクセスするために作成したサービスアカウントの名前が cicd-client である場合、以下のコマンドを実行します。

      $ oc policy add-role-to-user edit system:serviceaccount:fuse-online-north:cicd-client`
  5. syndesis カスタムリソースを編集します。

    1. 以下のコマンドを実行します。通常、エディターでリソースが開かれます。

      oc edit syndesis

    2. リソースを編集して、パブリック API を有効にし、routeHostname の設定としてエンドポイントを呼び出すための Fuse Online 環境のパブリックアドレスを指定します。Fuse Online のインストールに使用された default-cr.yml ファイルで、パブリック API が有効化され、エンドポイントのルートホスト名が指定されている場合は、リソースを編集する必要はありません。

      クラスターのセットアップにより、指定する必要のあるパブリックアドレスが決定されます。詳細は、ルートに関する OpenShift ドキュメントに記載されています。以下の例では、ルートのホスト名は minishift クラスターに対して有効です。

      spec:
        addons:
          publicApi:
            enabled: true
            routeHostname: public-syndesis.192.168.64.63.nip.io
    3. リソースを保存するか、そのまま閉じます。

      syndesis カスタムリソースを保存することにより、Fuse Online のインストールを担う syndesis-operator がパブリック API OAuth プロキシーサービスをデプロイするようトリガーされます。

      syndesis カスタムリソースを編集する必要がなければ、パブリック API OAuth プロキシーサービスはすでにデプロイされています。これは、Fuse Online のインストールに使用された default-cr.yml ファイルで publicApi が有効化され、そのルートが指定されたためです。

結果

OpenShift で、以下を確認できるようになります。

  • syndesis-public-oauthproxy デプロイメント設定の Pod
  • syndesis-public-oauthproxy サービス
  • syndesis-public-api ルート

この手順を実行した OpenShift プロジェクトでは、外部 CI/CD ツールで Fuse Online のパブリック REST API エンドポイントを使用して Fuse Online インテグレーションをエクスポートまたはインポートできます。

次のステップ

4.2. Fuse Online パブリック REST API エンドポイントのベース URL の説明

Fuse Online パブリック REST API エンドポイントのベース URL は、以下のようになります。

https://public-syndesis.192.168.64.42.nip.io/api/v1/public

Fuse Online 環境ごとに、ベース URL の最初の部分は異なります。OpenShift アプリケーションを作成して、これによりパブリック REST API エンドポイントへのアクセスを有効にする Fuse Online パブリック OAuth プロキシーを実行する場合、Fuse Online 環境のパブリックアドレスを指定します。このアドレスは、Fuse Online 環境で動作するエンドポイントを呼び出すベース URL の最初の部分です。以下に例を示します。

https://public-syndesis.192.168.64.42.nip.io

ベース URL の 2 つ目の部分は、すべての Fuse Online 環境で同じです。

/api/v1/public

Fuse Online のパブリック REST API は、3 つのリソースで動作するエンドポイントを提供します。

  • /integrations は、ベース URL で識別される Fuse Online 環境にあるインテグレーションです。
  • /connections は、ベース URL で識別される Fuse Online 環境にあるコネクションです。
  • /environments は、ベース URL で識別される Fuse Online 環境にある環境ラベルのセットです。

4.3. パブリック REST API エンドポイントを呼び出すためのシークレットトークンの取得

Fuse Online のパブリック REST API エンドポイントを呼び出すコマンドで、シークレットトークンを指定する必要があります。このトークンは、任意の Fuse Online 環境で Fuse Online パブリック REST API を公開したときに作成したサービスアカウントのものです。

前提条件

  • オンサイトの OCP で Fuse Online が稼働している必要があります。
  • エンドポイントを呼び出す Fuse Online 環境によって提供されるパブリック REST API を公開している必要があります。

手順

  1. この Fuse Online 環境のパブリック REST API を公開したときに作成したサービスアカウントのシークレットトークンの名前を取得します。たとえば、cicd-client がサービスアカウントの名前である場合、以下のコマンドを実行します。

    oc describe serviceaccount cicd-client

    これにより、以下のような 2 つのトークンの名前が含まれる、cicd-client サービスアカウントの情報の一覧が表示されます。

    Tokens:      cicd-client-token-gxb25
                 cicd-client-token-gxdnv
  2. いずれかのトークンの内容を表示します。以下に例を示します。

    oc describe secret cicd-client-token-gxb25

    これにより、token: とそれに続く長いランダムな文字を表示する Data セクションなど、情報の一覧が表示されます。これはサービスアカウントの 2 つのシークレットトークンの 1 つです。

  3. シークレットトークンをコピーし、ファイルに貼り付けて保存します。

結果

curl コマンドで指定するシークレットトークンは次のようになります。

-H 'Authorization: Bearer eyJhbGciOiJSUzI1NiIsImtpZCI6IiJ9.eyJpc3MiOiJrdWJlcm5ldGVzL3NlcnZpY2VhY2NvdW50Iiwia3ViZXJuZXRlcy5pby9zZXJ2aWNlYWNjb3VudC9uYW1lc3BhY2UiOiJzeW5kZXNpcyIsImt1YmVybmV0ZXMuaW8vc2VydmljZWFjY291bnQvc2VjcmV0Lm5hbWUiOiJzeW5kZXNpcy1jZC1jbGllbnQtdG9rZW4tMnZjNmwiLCJrdWJlcm5ldGVzLmlvL3NlcnZpY2VhY2NvdW50L3NlcnZpY2UtYWNjb3VudC5uYW1lIjoic3luZGVzaXMtY2QtY2xpZW50Iiwia3ViZXJuZXRlcy5pby9zZXJ2aWNlYWNjb3VudC9zZXJ2aWNlLWFjY291bnQudWlkIjoiNjUxMjYxNGMtMmYwMS0xMWU5LTk3OWEtNDI1YWNlMzY3MTcyIiwic3ViIjoic3lzdGVtOnNlcnZpY2VhY2NvdW50OnN5bmRlc2lzOnN5bmRlc2lzLWNkLWNsaWVudCJ9.uKsri0JSKJDbgHoQwAhBJSNuWKwJgjegf2QlrCkhxVssSK1zIMZQaF9P5a4R7ZcWRnrZ_345UTqxYVeRlfHWVH0PqBkD-n7PAS9dcKJIFdS1jUHOmL1FTGgc3YW-bz1SlWT93tvK1EhorZ4_-EBfXhSAP4Uumi5qAg3_QUTMDstq233NSwBKYtFOw3Pp1ys3p3y0hcaiLMimeCH60vR4iWvptqqzc5QDigHiPySZNWxs_5awZlwdoIDvR-nSj690aC-49UKFgyEEdzdFU4bI2W4hOyDyhN9fVaIAZQKeJUrJBU-lnFTHI_NAd2OwzOEBpWZuj31Za5w9fU4kf4UDGA'

次のステップ

保存されたファイルから、指定の Fuse Online 環境のパブリック REST API エンドポイントを呼び出すコマンドにトークンをコピーします。

4.4. インテグレーション ID の検索方法

特定のインテグレーションのみで動作する Fuse Online のパブリック REST API エンドポイントを呼び出すコマンドで、エンドポイントが操作するインテグレーションの ID を指定する必要があります。以下のいずれかを指定します。

  • インテグレーションの名前

    これは、Fuse Online コンソールで表示されているとおりに正確に指定する必要があります (例: timer-to-log)。インテグレーション名にスペースまたは特殊文字がある場合は、HTML エスケープ文字を指定する必要があります。

  • 内部インテグレーション ID

    この ID は、インテグレーションの概要を表示するときに Fuse Online コンソール URL に含まれます。インテグレーションの概要を表示するには、左側のナビゲーションパネルで Integrations をクリックします。インテグレーションのリストで、ID が必要なインテグレーションのエントリーをクリックします。

    ブラウザーでインテグレーションの概要が表示され、URL の末尾に /integrations/i-Lauq5ShznJ4LcuWwiwcz のような内容が表示されます。このインテグレーションの ID は i-Lauq5ShznJ4LcuWwiwcz です。

4.5. Fuse Online パブリックエンドポイントを呼び出す curl コマンドを指定するための形式

Fuse Online のパブリック REST API エンドポイントを呼び出す curl コマンドの形式は、以下のようになります。

curl [options] \
     -H "Content-Type: <media-type>" \
     -H "SYNDESIS-XSRF-TOKEN: awesome" \
     -H `Authorization: Bearer <token>` \
     <base-url><endpoint> \
     [--request <HTTP-method>] \
     [-d <data>] \
     [-o <filename>]

[options]

選択した curl オプションを指定します。

<media-type>

エクスポートおよびインポートエンドポイントに、multipart/form-data を指定します。他のすべてのエンドポイントに、application/json を指定します。

<token>

パブリック REST API を公開するときに作成した OpenShift サービスアカウントのシークレットトークンを指定します。

<base-url>

エンドポイントが操作するインテグレーション、コネクション、または環境ラベルのある Fuse Online 環境のベース URL を指定します。

<endpoint>

呼び出すエンドポイントを指定します。

[--request <HTTP-method>]

任意で、HTTP メソッドを指定します (例: --request POST)。

[-d <data>]

任意で、呼び出されるエンドポイントに応じて、エンドポイントが必要とする引数を指定します。たとえば、インテグレーションの環境ラベルを test に変更するには、-d `test` を指定します。

[-o <filename>]

任意で、出力が含まれるファイルの名前を指定する必要がある場合には、 curl-o オプションとファイル名を指定します (例: -o export.zip) 。

以下の curl コマンドは、指定する 1 つまたは複数の環境に対してインテグレーションをマーク付けする Fuse Online のパブリック API エンドポイントを呼び出します。

curl -v -k -L -H "Content-Type: application/json" -H "SYNDESIS-XSRF-TOKEN: awesome" -H 'Authorization: Bearer eyJhbGciOiJSUzI1NiIsImtpZCI6IiJ9.eyJpc3MiOiJrdWJlcm5ldGVzL3NlcnZpY2VhY2NvdW50Iiwia3ViZXJuZXRlcy5pby9zZXJ2aWNlYWNjb3VudC9uYW1lc3BhY2UiOiJzeW5kZXNpcyIsImt1YmVybmV0ZXMuaW8vc2VydmljZWFjY291bnQvc2VjcmV0Lm5hbWUiOiJzeW5kZXNpcy1jZC1jbGllbnQtdG9rZW4tMnZjNmwiLCJrdWJlcm5ldGVzLmlvL3NlcnZpY2VhY2NvdW50L3NlcnZpY2UtYWNjb3VudC5uYW1lIjoic3luZGVzaXMtY2QtY2xpZW50Iiwia3ViZXJuZXRlcy5pby9zZXJ2aWNlYWNjb3VudC9zZXJ2aWNlLWFjY291bnQudWlkIjoiNjUxMjYxNGMtMmYwMS0xMWU5LTk3OWEtNDI1YWNlMzY3MTcyIiwic3ViIjoic3lzdGVtOnNlcnZpY2VhY2NvdW50OnN5bmRlc2lzOnN5bmRlc2lzLWNkLWNsaWVudCJ9.uKsri0JSKJDbgHoQwAhBJSNuWKwJgjegf2QlrCkhxVssSK1zIMZQaF9P5a4R7ZcWRnrZ_345UTqxYVeRlfHWVH0PqBkD-n7PAS9dcKJIFdS1jUHOmL1FTGgc3YW-bz1SlWT93tvK1EhorZ4_-EBfXhSAP4Uumi5qAg3_QUTMDstq233NSwBKYtFOw3Pp1ys3p3y0hcaiLMimeCH60vR4iWvptqqzc5QDigHiPySZNWxs_5awZlwdoIDvR-nSj690aC-49UKFgyEEdzdFU4bI2W4hOyDyhN9fVaIAZQKeJUrJBU-lnFTHI_NAd2OwzOEBpWZuj31Za5w9fU4kf4UDGA'
https://public-syndesis.192.168.64.42.nip.io/api/v1/public/integrations/timer-to-log/tags -d '["test","staging"]' --request PUT

例の curl コマンドでは、以下が行われます。

  • コマンドの最後にある URL は、呼び出すエンドポイントの Fuse Online 環境を識別します。
  • timer-to-log は、指定した環境の timer-to-log インテグレーションをマーク付けすることを示します。
  • test および staging を指定すると、これらの環境の timer-to-log インテグレーションがマーク付けされます。