IBM Cloud Docs

このチュートリアルでは、Object Storage CLI を使用して IBM Cloud® Code Engine イベントをサブスクライブする方法を学習します。

分散環境では多くの場合、他のコンポーネント (通常、イベント・プロデューサーと呼ばれる) で生成されたメッセージ (イベント) に対応する処理をアプリケーションまたはジョブに行わせます。 Code Engine では、イベント・プロデューサーをサブスクライブすることで、アプリケーションまたはジョブが関心対象のイベントを受信できるようになります。イベント情報は、アプリケーションについては POST HTTP 要求、ジョブについては環境変数として受信されます。

開始前に

すべてのCode Engineユーザーは、従量課金 (PAYG) アカウントを持っている必要があります。チュートリアルでは、費用が発生する場合があります。コスト見積もりツールを使用して、使用量の見積もりに基づいてコスト見積もりを生成してください。詳しくは、 Code Engine 価格設定を参照してください。

Object Storage のバケットとリージョンの決定

Object Storage イベント・プロデューサーは、IBM Cloud Object Storage バケット内のオブジェクトに対する操作に基づいてイベントを生成します。

Object Storage プラグイン CLI をインストールします。
```
ibmcloud plugin install cloud-object-storage
```
Object Storage リソース・インスタンスを作成します。例えば、IBM Cloud ライト・サービス・プランを使用する、mycloud-object-storage という名前の Object Storage リソースを作成します。
```
ibmcloud resource service-instance-create mycloud-object-storage cloud-object-storage lite global
```
作成した Object Storage リソース・インスタンスの詳細を表示します。この詳細を使用して、Object Storage インスタンスから CRN (クラウド・リソース名) を取得します。 CRN は、使用する Object Storage インスタンスを指定します。 CRN は、ID コマンドの出力に含まれている ibmcloud resource service-instance COS_INSTANCE_NAME フィールドの値です。
```
ibmcloud resource service-instance mycloud-object-storage
```
出力例
```
Name:                  mycloud-object-storage
ID:                    crn:v1:bluemix:public:cloud-object-storage:global:a/ab9d57f699655f028880abcd2ccdb524:910b727b-abcd-4a73-abcd-77c68bfeabcd::
GUID:                  910b727b-abcd-4a73-abcd-77c68bfeabcd
Location:              global
Service Name:          cloud-object-storage
Service Plan Name:     lite
Resource Group Name:   Default
State:                 active
Type:                  service_instance
Sub Type:
Created at:            2020-10-14T19:09:22Z
Created by:            user@us.ibm.com
Updated at:            2020-10-14T19:09:22Z
[...]
```
Object Storage インスタンス名が分からない場合は、ibmcloud resource service-instances --service-name cloud-object-storage を実行して、Object Storage インスタンスのリストを表示します。

Object Storage インスタンスについて詳しくは、IBM Cloud Object Storage 入門を参照してください。
処理する Object Storage を指定するように、前のステップで見つけた Object Storage CRN を構成します。必ず、crn: で始まる ID 全体をコピーしてください。この例では、--force オプションを使用して、指定された CRN が構成に使用されるよう強制します。これは、複数の Object Storage インスタンスがある場合に役立ちます。
```
ibmcloud cos config crn --crn CRN --force
```
出力例
```
Saving new Service Instance ID...
OK
Successfully stored your service instance ID.
```
サブスクライブするバケットを識別します。 Object Storage インスタンスと関連付けられているバケットのリストを表示するには、以下のようにします。
```
ibmcloud cos buckets
```
バケットを作成するには、以下のようにします。
```
ibmcloud cos bucket-create -bucket BUCKET_NAME
```
Object Storage バケットのロケーションとプランを識別します。例えば、mybucket バケットを使用します。
```
ibmcloud cos bucket-location-get --bucket mybucket
```
出力例
```
Details about bucket mybucket:
Region: us-south
Class: Standard
```

Object Storage バケットは、Code Engine プロジェクトと同じリージョンにあるリージョン・バケットでなければなりません。

Code Engine への通知マネージャーの役割の割り当て

Object Storage サブスクリプションを作成するには、その前に Code Engine プロジェクトに通知マネージャー役割を割り当てておく必要があります。通知マネージャーの役割を持つ Code Engine は、Object Storage のバケットの通知を表示、変更、および削除できます。

通知マネージャー役割を割り当てることができるのは、アカウント管理者だけです。

使用する Code Engine プロジェクトを識別します。 ibmcloud ce project list コマンドを使用すると、プロジェクトのリストを表示できます。現行コンテキストとしてプロジェクトを選択するには、ibmcloud ce project select コマンドを使用します。例えば、myproject という名前のプロジェクトを選択するには、次のようにします
```
ibmcloud ce project select -n myproject
```

ibmcloud iam authorization-policy-create コマンドを使用して、通知マネージャー役割を割り当てます。

例えば、myproject という名前の Object Storage インスタンスの mycosinstance という名前のプロジェクトに通知マネージャー役割を割り当てる場合は、次のようにします。

ibmcloud iam authorization-policy-create codeengine cloud-object-storage "Notifications Manager" --source-service-instance-name PROJECT --target-service-instance-name COS-INSTANCE

通知マネージャーの役割をプロジェクトに割り当てた後、Object Storage インスタンスのリージョン・バケットのうち、プロジェクトと同じリージョンにあるものに対して Object Storage サブスクリプションを作成できるようになります。

以下の表は、この例の iam authorization-policy-create コマンドで使用されるオプションの要約です。コマンドとそのオプションについて詳しくは、ibmcloud iam authorization-policy-create コマンドを参照してください。

iam authorization-policy-create コマンドのコンポーネント
コマンド・オプション	説明
`codeengine`	アクセスを許可されるソース・サービス。
`cloud-object-storage`	ソース・サービスがアクセスを許可されるターゲット・サービス。
`Notifications Manager`	ソース・サービスのアクセス権限を提供する役割。
`source-service-instance-name`	アクセスを許可する `codeengine` プロジェクトの名前。
`target-service-instance-name`	アクセスする `cloud-object-storage` インスタンスの名前。

通知マネージャーの役割が設定されていることを確認します。

ibmcloud iam authorization-policies

出力例

ID:                        abcd1234-a123-b456-bdd9-849e337c4460
Source service name:       codeengine
Source service instance:   1234abcd-b456-c789-a7c5-ef82e56fb24c
Target service name:       cloud-object-storage
Target service instance:   a1b2c3d4-cbad-567a-8cea-77c68bfe97c9
Roles:                     Notifications Manager

アプリ (またはジョブ) の作成

イベントを使用してアプリやジョブをトリガーできますが、このチュートリアルではアプリを使用します。

cos-app と呼ばれるイメージを指定して ibmcloud ce app create コマンドを使用し、cos-listen という名前のアプリケーションを作成します。このアプリは、イベントが届くたびにそれをログに記録します。このイメージは、 IBM Cloud Code Engine GitHub リポジトリーのサンプルから入手できる cos-listen.go から作成されています。

ibmcloud ce app create --name cos-app --image icr.io/codeengine/cos-listen

ibmcloud ce application get --name cos-app を実行して、アプリが Ready 状態であることを確認します。アプリケーションが正常にデプロイされたことが状況要約に反映されている場合、アプリケーションは作動可能状態です。

このアプリケーションについて詳しくは、 IBM Cloud Object Storage の README ファイルを参照してください。

サブスクリプションの作成

アプリが Ready になったら、Object Storage サブスクリプションを作成し、ibmcloud ce sub cos create コマンドを使用して Object Storage イベントの受信を開始できるようにします。

例えば、cos-sub という Object Storage サブスクリプションを作成します。このサブスクリプションは、任意のタイプのバケット操作を mybucket バケットから cos-app というアプリケーションに転送します。

ibmcloud ce sub cos create --name cos-sub --destination cos-app --bucket mybucket --event-type all

ibmcloud ce sub cos get -n cos-sub コマンドを実行して、サブスクリプションに関する情報を確認します。

出力例

デフォルトでは、ibmcloud ce sub cos get コマンドは 2 つの部分を返します。最初の部分には、サブスクリプション名、宛先、接頭部、接尾部、およびイベント・タイプなどの、Object Storage サブスクリプションに関連した情報が入ります。 2 番目の部分には、デバッグのために使用できる、Object Storage サブスクリプションに関するリソース関連のイベント情報が入ります。デフォルトで、イベント情報は、それが発生してから 1 時間使用できます。

Getting COS event subscription 'cos-sub'...
OK
Name:          cos-sub
ID:            abcdefgh-abcd-abcd-abcd-1a2b3c4d5e6f
Project Name:  myproject
Project ID:    01234567-abcd-abcd-abcd-abcdabcd1111
Age:           4m16s
Created:       2021-02-01T13:11:31-05:00
Destination:  App:cos-app
Bucket:       mybucket
EventType:    all
Ready:        true

Conditions:
    Type            OK    Age  Reason
    CosConfigured   true  38s
    Ready           true  38s
    ReadyForEvents  true  38s
    SinkProvided    true  38s

Events:
    Type    Reason          Age  Source                Messages
    Normal  CosSourceReady  39s  cossource-controller  CosSource is ready

デフォルトで、subscription cos create コマンドは、最初に宛先アプリケーションが存在するかどうかを確認します。指定したアプリ名がプロジェクト内に存在しないために宛先を確認できなかった場合、subscription cos create コマンドはエラーを返します。最初にアプリケーションを作成することなくサブスクリプションを作成する場合は、--force オプションを使用します。 --force オプションを使用することで、コマンドは宛先の確認をバイパスします。宛先アプリが作成されるまでサブスクリプションの Ready フィールドに false が表示されることに注意してください。宛先アプリが作成されると、サブスクリプションの状態は自動的に Ready: true になります。

サブスクリプションが作成されてから subscription cos create コマンドにより結果が報告されるまでの間に、この subscription cos create コマンドはサブスクリプションの状況を繰り返しポーリングして、その準備状況を確認します。デフォルトで、状況を確認するこの継続的ポーリングは 15 秒間続くとタイムアウトになります。サブスクリプションの状況が Ready:true として返されれば成功を、それ以外の場合はエラーを示します。 subscription cos create コマンドがタイムアウトになるまでに待機する時間は、--wait-timeout オプションを使用して変更することができます。また、--no-wait オプションを false に設定することで状況のポーリングをバイパスすることもできます。

ヘッダーおよび本文について詳しくは、イベントの HTTP ヘッダーおよび本文の情報を参照してください。

サブスクリプションはアプリケーションのスケーリングに影響を及ぼすことに留意してください。詳しくは、アプリケーション・スケーリングの構成を参照してください。

サブスクリプションのテスト

.txt ファイルをバケットにアップロードします。例えば、ibmcloud cos object-put コマンドを使用して、sample.txt の値として sample を指定して、バケットに --key オブジェクトをアップロードできます。
```
ibmcloud cos object-put --bucket mybucket --key sample --body sample.txt
```
ibmcloud ce app logs コマンドを使用して、処理されたイベントを表示します。
```
ibmcloud ce app logs --name cos-app
```
出力例

このコマンドは、宛先アプリに転送されたイベントに関する情報を含むログ・ファイルを返します。以下の出力から、Write という名前のバケットにある sample オブジェクトに対して mybucket 操作が実行されたことが分かります。
```
Body: {"bucket":"mybucket","endpoint":"","key":"sample","notification":{"bucket_name":"mybucket","content_type":"text/plain","event_type":"Object:Write","format":"2.0","object_length":"1960","object_name":"sample","request_id":"103dd6f7-dd7b-4f49-86db-c2ff4b678b0a","request_time":"2021-02-11T16:57:42.373Z"},"operation":"Object:Write"}
```

Object Storage サブスクリプションの更新

Object Storage サブスクリプションの作成に成功して Object Storage サブスクリプションがイベントを処理できる状態になったので、次に ibmcloud ce sub cos update コマンドを使用して Object Storage サブスクリプションを更新します。例えば、バケット内のオブジェクトのサブセットで特定の操作が発生したときにのみ実行されるように、サブスクリプションを変更できます。

名前の接頭部が delete のファイルで test 操作が発生する場合にのみイベントを転送するように Object Storage サブスクリプションを更新するには、次のようにします。
```
ibmcloud ce sub cos update --name cos-sub --event-type delete --prefix test
```

ibmcloud ce sub cos get コマンドを実行して、サブスクリプションに関する情報を確認します。

ibmcloud ce sub cos get --name cos-sub

出力例

この出力では、Prefix と EventType の更新値が表示されることを確認できます。

Getting COS event subscription 'cos-sub'...
OK
Name:          cos-sub
ID:            abcdefgh-abcd-abcd-abcd-1a2b3c4d5e6f
Project Name:  myproject
Project ID:    01234567-abcd-abcd-abcd-abcdabcd1111
Age:           4m16s
Created:       2021-02-01T13:11:31-05:00
Destination:  App:cos-app
Bucket:       mybucket
EventType:    delete
Prefix:       test
Ready:        true

Conditions:
    Type            OK    Age  Reason
    CosConfigured   true  24m
    Ready           true  24m
    ReadyForEvents  true  24m
    SinkProvided    true  24m

Events:
    Type    Reason          Age               Source                Messages
    Normal  CosSourceReady  9s (x2 over 24m)  cossource-controller  CosSource is ready

接頭部 test があるオブジェクトをバケットから削除します。例えば、名前 (またはキー) が test2.txt のファイルを削除します。 ibmcloud cos object-delete コマンドを使用してバケットからオブジェクトを削除するか、Object Storage コンソールを使用できます。
ibmcloud ce app logs コマンドを使用して、処理されたイベントを表示します。
```
ibmcloud ce app logs --name cos-app
```
出力例

このコマンドは、宛先アプリに転送されたイベントに関する情報を含むログ・ファイルを返します。以下の出力から、Delete という名前のバケットにある .txt オブジェクトに対して mybucket 操作が実行されたことが分かります。
```
Body: {"bucket":"mybucket","endpoint":"",""key":"test2.txt","notification":{"bucket_name":"mybucket","event_type":"Object:Delete","format":"2.0","object_length":"41","object_name":"test2.txt","request_id":"c1099857-f1f3-4d74-9ac4-8d374582f77d","request_time":"2021-09-15T15:22:01.205Z"},"operation":"Object:Delete"}
```

Object Storage のクリーンアップのチュートリアル

Object Storage サブスクリプションとアプリを削除する準備ができましたか? ibmcloud ce app delete コマンドと ibmcloud ce sub cos delete コマンドを使用することができます。

サブスクリプションを削除するには、以下のようにします。

ibmcloud ce sub cos delete --name cos-sub

アプリケーションを削除するには、以下のようにします。

ibmcloud ce app delete --name cos-app

Object Storage バケットとサービス・インスタンスを削除する準備ができましたか? バケットは、ibmcloud cos bucket-delete コマンドを使用して削除できます。 Object Storage サービス・インスタンスを削除するには、 ibmcloud resource service-instance-delete コマンドを使用します。