訂閱 Object Storage 的活動

透過本教學，您可以學習如何使用 IBM Cloud® Code Engine CLI 訂閱 Object Storage 的事件。

在分散式環境中，您通常希望應用程式或工作對從其他元件 (通常稱為事件生產者) 產生的訊息 (事件) 做出反應。透過 Code Engine，您的應用程式或工作可透過訂閱事件產生者，接收感興趣的事件。應用程式會透過 POST HTTP 請求接收事件資訊，而工作則會透過環境變數接收事件資訊。

開始之前

所有 Code Engine 使用者均須擁有一個「隨用隨付」帳戶。指導教學可能會產生成本。請使用「成本估算器」，根據您的預估使用量生成成本估算。如需更多資訊，請參閱 Code Engine 價格資訊。

判定 Object Storage 儲存區及地區

Object Storage 事件產生器會根據對 IBM Cloud Object Storage 儲存桶中物件所執行的操作來產生事件。

安裝 Object Storage 外掛程式 CLI。

ibmcloud plugin install cloud-object-storage

建立 Object Storage 資源實例。例如，建立名為 mycloud-object-storage 且使用 IBM Cloud Lite 服務方案的 Object Storage 資源。
```
ibmcloud resource service-instance-create mycloud-object-storage cloud-object-storage lite global
```

顯示您所建立 Object Storage 資源實例的詳細資料。使用詳細資料從 Object Storage 實例取得 CRN (雲端資源名稱)。 CRN 會識別您要使用的 Object Storage 實例。 CRN 是 ibmcloud resource service-instance COS_INSTANCE_NAME 指令輸出中 ID 欄位的值。

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 CRN，以指定要使用的 Object Storage 實例。請務必複製整個 ID，從 crn: 開始。此範例使用 --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 指令來指派「通知管理員」角色。

例如，針對名為 mycosinstance 的 Object Storage 實例，將通知管理員角色指派給名為 myproject 的專案，

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-listen 的映像檔，以 ibmcloud ce app create 指令建立名為 cos-app 的應用程式。此應用程式會在每一個事件到達時記載它。此映像檔是從 cos-listen.go 建置，可從 Samples for IBM Cloud Code Engine GitHub repo取得。

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 檔。

建立訂閱

Object Storage 當您的應用程式準備就緒後，您可以建立一個「Object Storage」訂閱，以便透過 ibmcloud ce sub cos create 命令來接收xml-ph-0001@deepl.internal事件。

例如，建立稱為 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 指令會傳回兩個部分。第一部分包括 Object Storage 訂閱相關資訊，例如訂閱名稱、目的地、字首、字尾及事件類型。第二部分包括可用於除錯目的之 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，則它會報告成功，否則會報告錯誤。您可以使用 --wait-timeout 選項來變更 subscription cos create 指令在逾時之前等待的時間量。您也可以將 --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

輸出範例

此指令會傳回日誌檔，其中包含已轉遞至目的地應用程式之事件的相關資訊。從下列輸出中，您可以看到已對名稱為 mybucket 的儲存區中的 sample 物件執行 Write 作業。

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」訂閱已成功建立，且「Object Storage」訂閱已準備好處理事件，您可以使用 ibmcloud ce sub cos update 命令來更新 xml-ph-0002@deepl.internal 訂閱。例如，您可以將訂閱變更為僅在儲存區中物件子集上發生特定作業時執行。

僅當 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

輸出範例

此指令會傳回日誌檔，其中包含已轉遞至目的地應用程式之事件的相關資訊。從下列輸出中，您可以看到已對名稱為 mybucket 的儲存區中的 .txt 物件執行 Delete 作業。

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 指令。