コンソールからのアプリケーションのIBM Cloud Object Storageイベントへのサブスクライブ

コンソールから、アプリケーションのIBM Cloud Object Storageイベント・サブスクリプションを作成および更新できます。

開始前に

• プロジェクトを作成します。
• アプリケーションを作成します。 例えば、icr.io/codeengine/cos-eventイメージを使用するmyappというアプリケーションを作成します。 この画像は cos-listen.go から作成されており、 IBM Cloud Code Engine GitHub レポジトリのサンプルから入手できます。

コンソールからアプリケーションのIBM Cloud Object Storageイベント・サブスクリプションを作成および更新するには、以下のステップを実行します。

1. Code Engine のプロジェクトページから、お客様のプロジェクトにアクセスしてください。

2. 「概要」ページで、**「イベント・サブスクリプション (Event subscriptions)」**をクリックします。

3. 「イベント・サブスクリプション (Event subscriptions)」ページで**「作成」**をクリックして、サブスクリプションを作成します。

4. 「イベント・サブスクリプションの作成」ページで、以下の手順を実行します。

   1. イベント・タイプの場合は、Cloud Object Storageタイルを選択します。 **「次へ」**をクリックします。
   2. 一般には、Object Storageサブスクリプションの名前 (例えば、mycos) を指定します。 オプションで、イベント属性を指定できます。 Object Storageイベント・コンシューマーがアプリケーションの場合、イベント属性は HTTP ヘッダーとして使用できることに注意してください。 イベントのコンシューマーがジョブの場合は、使用できるイベント属性は環境変数になります。 **「次へ」**をクリックして、先に進みます。
   3. バケット・イベントの詳細には、既存のObject Storageバケットの名前を選択または入力します。 オブジェクトの変更のタイプを指定し、オプションでオブジェクト名の接頭部または接尾部を指定して、サブスクリプションのイベントをトリガーするバケット内のオブジェクトをフィルターに掛けます。 **「次へ」**をクリックして、先に進みます。
   4. イベント・コンシューマーには、イベントを受信するアプリケーションを指定します。 定義済みのアプリケーションとジョブのリストから選択できることに注意してください。 この例では、icr.io/codeengine/cos-listenイメージを参照するmyappアプリケーションを使用します。 アプリが存在しない場合は、Object Storageサブスクリプションの作成後に、アプリケーションの名前と アプリケーションの作成を指定できます。 アプリケーションの場合のみ、オプションでパスを指定できます。 デフォルトでは、イベントは、宛先アプリケーションのルート URL にルーティングされます。 パスを指定すると、アプリ内の別の宛先にイベントを送信できます。 例えば、サブスクリプション・パスに/eventsが指定されている場合、イベントはhttps://<base application URL>/eventsに送信されます。 **「次へ」**をクリックして、先に進みます。
   5. 概要の場合、Object Storageイベント・サブスクリプションの設定を確認し、必要に応じて変更します。 準備ができたら、作成をクリックしてObject Storageサブスクリプションを作成します。

5. これでObject Storageサブスクリプションが作成されたので、「イベント・サブスクリプション」ページの定義済みサブスクリプションのリストの表示に移動します。

6. サブスクリプションを更新するには、Object Storageサブスクリプション・ページにナビゲートします。 イベント・サブスクリプションのページで、更新するサブスクリプションの名前をクリックします。

7. Object Storage サブスクリプション・ページから、オブジェクト変更のタイプをdeleteオブジェクト変更のみに変更します。 バケット・イベントの詳細 タブから、delete タイプのオブジェクト変更のみを選択します。 **「保存」**をクリックして変更を保存します。

8. myappアプリケーションは、ログ・ファイルに情報を出力するサンプルcos-listenアプリケーションを参照するため、ログを表示できます。 オブジェクトがバケットから削除されると、アプリ・ログに削除のイベントが表示されます。 コンソールでのアプリのログの表示を参照してください。

特定のバケットを参照するIBM Cloud Object Storageイベント・サブスクリプションを定義した後は、このサブスクリプションを別のバケットを使用するように更新できません。 目的のバケットを参照するには、新しいサブスクリプションを作成しなければなりません。

CLI を使用したアプリケーションのIBM Cloud Object Storageイベントのサブスクライブ

開始前に

• Code Engine の CLI 環境をセットアップします。

• プロジェクトを作成して使用できるようにします。

• アプリケーションを作成します。 例えば、icr.io/codeengine/cos-listenイメージを使用するmyappというアプリケーションを作成します。 この画像は cos-listen.go から作成されており、 IBM Cloud Code Engine GitHub レポジトリのサンプルから入手できます。 以下に例を示します。

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

1. ibmcloud ce subscription cos createコマンドを使用して、アプリケーションをIBM Cloud Object Storageイベント・プロデューサーに接続します。 以下に例を示します。

   ibmcloud ce subscription cos create --name mycosevent --destination-type app --destination myapp --bucket mybucket
   

2. サブスクリプションが作成されたら、**subscription cos get**コマンドを実行してサブスクリプションの詳細を確認します。

   ibmcloud ce subscription cos get --name mycosevent
   

   出力例

   Getting COS source 'mycosevent'...
   OK
   
   Name:          mycosevent
   ID:            abcdefgh-abcd-abcd-abcd-1a2b3c4d5e6f
   Project Name:  myproject
   Project ID:    01234567-abcd-abcd-abcd-abcdabcd1111
   Age:           59s
   Created:       2021-03-01T20:08:36-06:00
   
   Destination:  App:myapp
   Bucket:       mybucket
   Event Type:   all
   Ready:        true
   
   Conditions:
       Type            OK    Age  Reason
       CosConfigured   true  55s
       Ready           true  55s
       ReadyForEvents  true  55s
       SinkProvided    true  55s
   
   Events:
       Type     Reason           Age      Source                Messages
       Normal   FinalizerUpdate  61s      cossource-controller  Updated "mycosevent" finalizers
   

バケットを変更するたびに、アプリが通知を受け取るようになりました。

チュートリアルを試すには、 Object Storage イベントのサブスクライブを参照してください。 コード・サンプルがさらに必要ですか? IBM Cloud Code Engine GitHub repoを確認してください。

コンソールでのアプリケーションのイベント情報の表示

イベント・サブスクリプションに関する情報を表示するには、次のようにします。

1. Code Engine のプロジェクトページから、お客様のプロジェクトにアクセスしてください。
2. 「概要」ページで、**「イベント・サブスクリプション (Event subscriptions)」**をクリックし、定義済みのサブスクリプションのリストを表示します。

アプリケーションがサンプル cos-listen アプリケーションのように情報をログ・ファイルに出力する場合は、イベント・コンシューマー・アプリケーションのログ・ファイルを表示します。 コンソールでのアプリのログの表示を参照してください。

CLI でのアプリケーションのイベント情報の表示

cos-listen アプリケーションと同じように、アプリケーションが情報をログ・ファイルに出力する場合は、CLI コマンド ibmcloud ce app logs を使用して、送信された情報を表示できます。

アプリケーションのイベント情報を表示する前に、まず Object Storage イベントを作成しておく必要があります。 バケットに対して変更を加えます。

前の例で作成したアプリケーションのログを表示するには、以下のようにします。

ibmcloud ce application logs --application myapp

出力例

Getting logs for all instances of application 'myapp'...
OK

myapp-a2mvv-1-deployment-d97dcd6cf-zc9lg/user-container:
Listening on port 8080
2021-04-13 19:43:45 - Received:

Body: {"bucket":"mybucket","endpoint":"","key":"Notes.rtf","notification":{"bucket_name":"mybucket","content_type":"text/rtf","event_type":"Object:Write","format":"2.0","object_etag":"2944035e54ee1bdc423848c8eaf05e86","object_length":"4642","object_name":"NOtes.rtf","request_id":"6abc7123-382d-4115-98e8-7568b2cc03f8","request_time":"2021-04-13T19:43:36.610Z"},"operation":"Object:Write"}

アプリのログ情報は1時間しか保存されないことに注意してください。 ロギングについて詳しくは、ログの表示を参照してください。

コード・サンプルがさらに必要ですか? IBM Cloud Code Engine GitHub repoを確認してください。

アプリケーションに配信されるイベントの IBM Cloud Object Storage ヘッダーと本文の情報

アプリケーションに配信されるすべてのイベントは、HTTP メッセージとして受信されます。 イベントには特定の HTTP ヘッダーが含まれており、イベントの本文 (ビジネス・ロジック) を確認しなくても、イベントに関する重要な情報を素早く判別することができます。 詳細については 、 CloudEvents の仕様書をご覧ください。

ce-id:  3fb2c04e-a660-4640-8899-b82efb8169b6
ce-source: https://cloud.ibm.com/catalog/services/cloud-object-storage/mybucket
ce-specversion: 1.0
ce-subject: object-69-144
ce-time: 2021-08-17T20:22:02.917Z
ce-type: com.ibm.cloud.cos.document.delete

{
  "bucket": "mybucket",
  "endpoint": "",
  "key": "object-69-144",
  "notification": {
    "bucket_name": "mybucket",
    "content_type": "image/svg+xml",
    "event_type": "Object:Delete",
    "format": "2.0",
    "object_etag": "f3a9dbde30fdf48abc23e5f8b485d6e5",
    "object_length": "1064391",
    "object_name": "object-69-144",
    "request_id": "67a2048a-abcd-abcd-9e0c-968744094b85",
    "request_time": "2021-08-17T20:22:02.917Z"
  },
  "operation": "Object:Delete"
}

コンソールからのジョブに関するIBM Cloud Object Storageイベントのサブスクライブ

コンソールから、ジョブのIBM Cloud Object Storageイベント・サブスクリプションを作成および更新できます。

開始前に

• プロジェクトを作成します。
• ジョブを作成します。 例えば、icr.io/codeengine/codeengineイメージを使用するmyjobという名前のジョブを作成します。 この画像は codeengine.go から作成されており、 IBM Cloud Code Engine GitHub レポジトリのサンプルから入手できます。

コンソールからジョブの IBM Cloud Object Storage イベント購読を作成または更新するには、以下の手順に従います

1. Code Engine のプロジェクトページから、お客様のプロジェクトにアクセスしてください。

2. 「概要」ページで、**「イベント・サブスクリプション (Event subscriptions)」**をクリックします。

3. 「イベント・サブスクリプション (Event subscriptions)」ページで**「作成」**をクリックして、サブスクリプションを作成します。

4. イベント購読の作成ページから、以下の手順を完了します

   1. イベント・タイプの場合は、Cloud Object Storageタイルを選択します。 **「次へ」**をクリックします。

   2. 一般には、Object Storageサブスクリプションの名前 (例えば、mycos-job) を指定します。 オプションで、イベント属性を指定できます。 イベント・コンシューマーがジョブの場合、イベント属性は環境変数として使用可能です。 **「次へ」**をクリックして、先に進みます。

   3. バケットイベントの詳細については、既存の Object Storage バケットの名前を選択または入力し、イベントをトリガーしたいオブジェクトの変更の種類を指定します。

      オブジェクト変更タイプでは、 Object Storage オブジェクトに対するアクションのイベントを受信するタイミングを指定します。オブジェクト変更のタイプとして、以下のいずれか、または両方を選択できます

      • 新しいオブジェクトが作成または更新されるたびにイベントを受信するには 、Create and update を使用します。 更新されたオブジェクトについては、選択されたバケット内の既存のオブジェクトが再アップロードされます。
      • 既存のオブジェクトがバケットから削除されるたびにイベントを受信するには 、[削除] を使用します。

      また、オプションとして、バケット内のオブジェクトをフィルタリングしてサブスクリプションのイベントをトリガーするために、オブジェクト名の接頭辞または接尾辞を指定することもできます。 オブジェクト名の接頭語またはオブジェクト名の接尾語の値を指定して、イベントを受信したいオブジェクト名の先頭（接頭語）または末尾（接尾語）に一致する文字列を示します。 この値は、 Object Storage バケット内のイベントをトリガーするオブジェクトを、指定した接頭辞または接尾辞で始まるか終わるファイル名に制限します。 ワイルドカード文字や正規表現は使用しないでください。プレフィックスとサフィックスにはプレーンテキストのみを指定してください（例えば、 abc で始まるすべてのオブジェクトを示すには、 *abc ではなく、 abc を指定します）。 さらに、ファイル名にはファイル拡張子を含めます（例えば、 json を接尾辞として指定した場合、 abc.json などのファイルは処理されますが、 abcjson.txt は処理されません）。

      **「次へ」**をクリックして、先に進みます。

   4. イベント・コンシューマーには、イベントを受信するジョブを指定します。 定義済みのジョブのリストから選択できることに注意してください。 この例では、icr.io/codeengine/codeengineイメージを参照するmyjobジョブを使用します。 ジョブが存在しない場合は、Object Storageサブスクリプションの作成後に、ジョブの名前とジョブの作成を指定できます。 **「次へ」**をクリックして、先に進みます。

   5. 概要の場合、Object Storageイベント・サブスクリプションの設定を確認し、必要に応じて変更します。 準備ができたら、作成をクリックしてObject Storageサブスクリプションを作成します。

5. これでObject Storageサブスクリプションが作成されたので、「イベント・サブスクリプション」ページの定義済みサブスクリプションのリストの表示に移動します。

6. サブスクリプションを更新するには、Object Storageサブスクリプション・ページにナビゲートします。 イベント・サブスクリプションのページで、更新するサブスクリプションの名前をクリックします。

7. Object Storage サブスクリプション・ページから、オブジェクト変更のタイプをdeleteオブジェクト変更のみに変更します。 バケット・イベントの詳細タブからは、deleteタイプのオブジェクト変更のみを選択します。 **「保存」**をクリックして変更を保存します。

8. myjobジョブは、ログ・ファイルに情報を出力するサンプルicr.io/codeengine/codeengineジョブを参照するので、ログを表示できます。 オブジェクトがバケットから削除されると、ジョブ実行のログでその削除に関するイベントを確認できます。 コンソールでのジョブのログの表示を参照してください。

サブスクリプションで作成されたジョブ実行は 10 分後に削除されます。

特定のバケットを参照するIBM Cloud Object Storageイベント・サブスクリプションを定義した後は、このサブスクリプションを別のバケットを使用するように更新できません。 目的のバケットを参照するには、新しいサブスクリプションを作成しなければなりません。

CLI を使用したジョブのIBM Cloud Object Storageイベントのサブスクライブ

開始前に

• Code Engine の CLI 環境をセットアップします。

• プロジェクトを作成して使用できるようにします。

• ジョブを作成します。 例えば、icr.io/codeengine/codeengineイメージを使用するmyjobという名前のジョブを作成します。 この画像は codeengine.go から作成されており、 IBM Cloud Code Engine GitHub レポジトリのサンプルから入手できます。

  ibmcloud ce job create --name myjob --image icr.io/codeengine/codeengine
  

1. ibmcloud ce subscription cos createコマンドを使用して、ジョブをIBM Cloud Object Storageイベント・プロデューサーに接続します。

   ibmcloud ce subscription cos create --name mycosevent --destination-type job --destination myjob --bucket mybucket
   

2. サブスクリプションが作成されたら、**subscription cos get**コマンドを実行してサブスクリプションの詳細を確認します。

   ibmcloud ce subscription cos get --name mycosevent
   

   出力例

   Getting COS source 'mycosevent'...
   OK
   
   Name:          mycosevent
   ID:            abcdefgh-abcd-abcd-abcd-1a2b3c4d5e6f
   Project Name:  myproject
   Project ID:    01234567-abcd-abcd-abcd-abcdabcd1111
   Age:           59s
   Created:       2021-03-01T20:08:36-06:00
   
   Destination Type:  job
   Destination:       myjob
   Bucket:       mybucket
   Event Type:   all
   Ready:        true
   
   Conditions:
       Type            OK    Age  Reason
       CosConfigured   true  55s
       Ready           true  55s
       ReadyForEvents  true  55s
       SinkProvided    true  55s
   
   Events:
       Type     Reason           Age      Source                Messages
       Normal   FinalizerUpdate  61s      cossource-controller  Updated "mycosevent" finalizers
   

バケットを変更するたびに、ジョブが通知を受け取るようになりました。

サブスクリプションで作成されたジョブ実行は 10 分後に削除されます。

チュートリアルを試すには、 Object Storage イベントのサブスクライブを参照してください。 コード・サンプルがさらに必要ですか? IBM Cloud Code Engine GitHub repoを確認してください。

コンソールでのジョブのイベント情報の表示

イベント・サブスクリプションに関する情報を表示するには、次のようにします。

1. Code Engine のプロジェクトページから、お客様のプロジェクトにアクセスしてください。
2. 「概要」ページで、**「イベント・サブスクリプション (Event subscriptions)」**をクリックし、定義済みのサブスクリプションのリストを表示します。

ジョブがサンプル codeengine ジョブのように情報をログ・ファイルに出力する場合は、イベント・コンシューマー・アプリケーションのログ・ファイルを表示します。 コンソールでのジョブのログの表示を参照してください。

CLI でのジョブのイベント情報の表示

ジョブがcodeengineジョブのように情報をログ・ファイルに出力する場合は、ibmcloud ce jobrun logsCLI コマンドを使用して、送信された情報を表示します。

ジョブでイベント情報を表示する前に、まず Object Storage イベントを作成しておく必要があります。 バケットに対して変更を加えます。

前の例のジョブのジョブ実行を確認するには、以下のようにします。

ibmcloud ce jobrun list

出力例

Listing job runs...
OK

Name         Failed  Pending  Requested  Running  Succeeded  Unknown  Age
myjob-pnz6m  0       0        0          0        1          0        39s

ジョブ実行名を指定して、ジョブ実行のログを表示します。

ibmcloud ce jobrun logs --jobrun myjob-pnz6m

出力例

Getting logs for all instances of job run 'myjob-pnz6m'...
Getting jobrun 'myjob-pnz6m'...
Getting instances of jobrun 'myjob-pnz6m'...
OK

myjob-pnz6m-0-0/myjob:
Hello from helloworld! I'm a batch job! Index: 0

Hello World from:
. ___  __  ____  ____
./ __)/  \(    \(  __)
( (__(  O )) D ( ) _)
.\___)\__/(____/(____)
.____  __ _   ___  __  __ _  ____
(  __)(  ( \ / __)(  )(  ( \(  __)
.) _) /    /( (_ \ )( /    / ) _)
(____)\_)__) \___/(__)\_)__)(____)

Some Env Vars:
--------------
CE_DATA={"bucket":"mybucket","endpoint":"","key":"Notes.rtf","notification":{"bucket_name":"mybucket","content_type":"text/rtf","event_type":"Object:Delete","format":"2.0","object_length":"4642","object_name":"Notes.rtf","request_id":"b59727ee-9c4e-446a-9261-5616f6d1283b","request_time":"2021-04-13T20:10:37.631Z"},"operation":"Object:Delete"}
CE_ID=b59727ee-9c4e-446a-9261-5616f6d1283b
CE_SOURCE=https://cloud.ibm.com/catalog/services/cloud-object-storage/mybucket
CE_SPECVERSION=1.0
CE_TIME=2021-04-13T20:10:37.631Z
CE_TYPE=com.ibm.cloud.cos.document.delete
CONTENT_TYPE=application/json
HOME=/root
HOSTNAME=myjob-pnz6m-0-0
JOB_INDEX=0
KUBERNETES_PORT=tcp://172.21.0.1:443
KUBERNETES_PORT_443_TCP=tcp://172.21.0.1:443
KUBERNETES_PORT_443_TCP_ADDR=172.21.0.1
KUBERNETES_PORT_443_TCP_PORT=443
KUBERNETES_PORT_443_TCP_PROTO=tcp
KUBERNETES_SERVICE_HOST=172.21.0.1
KUBERNETES_SERVICE_PORT=443
KUBERNETES_SERVICE_PORT_HTTPS=443
PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin
PWD=/
SHLVL=1

ジョブ実行のログ情報は1時間しか保存されないことに注意してください。 ロギングについて詳しくは、ログの表示を参照してください。

コード・サンプルがさらに必要ですか? IBM Cloud Code Engine GitHub repoを確認してください。

ジョブに配信されるイベントの環境変数

ジョブに配信されるすべてのイベントは、環境変数として受信されます。 これらの環境変数には、 CE_ の接頭辞が含まれ、 CloudEvents 仕様に基づいています。

各イベントには、イベントがジョブに配信されるたびに表示されるいくつかの共通の環境変数が含まれています。 各イベントの実際の変数のセットには、これより多くのオプションが含まれる可能性があります。 詳細およびその他の環境変数オプションについては 、 CloudEvent の属性を参照してください。

IBM Cloud Object Storage イベントに固有の環境変数について、以下の表で説明します。

{
"bucket":"mybucket",
"endpoint":"",
"key":"Notes.rtf",
"notification": {
    "bucket_name":"mybucket",
    "content_type":"text/rtf",
    "event_type":"Object:Delete",
    "format":"2.0",
    "object_length":"4642",
    "object_name":"Notes.rtf",
    "request_id":"b59727ee-9c4e-446a-9261-5616f6d1283b",
    "request_time":"2021-04-13T20:10:37.631Z"
},
"operation":"Object:Delete"}

CE_DATA={"bucket":"mybucket","endpoint":"","key":"Notes.rtf","notification":{"bucket_name":"mybucket","content_type":"text/rtf","event_type":"Object:Delete","format":"2.0","object_length":"4642","object_name":"Notes.rtf","request_id":"b59727ee-9c4e-446a-9261-5616f6d1283b","request_time":"2021-04-13T20:10:37.631Z"},"operation":"Object:Delete"}
CE_ID=b59727ee-9c4e-446a-9261-5616f6d1283b
CE_SOURCE=https://cloud.ibm.com/catalog/services/cloud-object-storage/mybucket
CE_SPECVERSION=1.0
CE_TIME=2021-04-13T20:10:37.631Z
CE_TYPE=com.ibm.cloud.cos.document.delete

コンソールからのサブスクリプションの削除

1. Code Engine のプロジェクトページから、お客様のプロジェクトにアクセスしてください。
2. 「概要」ページで、**「イベント・サブスクリプション (Event subscriptions)」**をクリックし、定義済みのサブスクリプションのリストを表示します。
3. アプリケーションまたはジョブから削除するサブスクリプションを、サブスクリプションのリストから削除します。

サブスクリプションに関連付けられているアプリまたはジョブを削除しても、サブスクリプションは削除されません。 アプリケーションまたはジョブ (あるいは同じ名前の別のアプリまたはジョブ) を再作成すると、サブスクリプションはそのアプリまたはジョブに再接続します。

CLI でのサブスクリプションの削除

ibmcloud ce subscription cos deleteコマンドを実行して、IBM Cloud Object Storageサブスクリプションを削除できます。

例えば、以下のコマンドを使用して、mycoseventという名前のIBM Cloud Object Storageサブスクリプションを削除します。

ibmcloud ce subscription cos delete --name mycosevent

サブスクリプションに関連付けられているアプリまたはジョブを削除しても、サブスクリプションは削除されません。 代わりに、サブスクリプションはアプリまたはジョブの可用性に依存するため、 falseの作動可能状態に移行します。 アプリケーションまたはジョブ (あるいは同じ名前の別のアプリまたはジョブ) を再作成すると、サブスクリプションは再接続され、作動可能状態はtrueになります。