Assinando eventos do Object Storage

Com este tutorial, é possível aprender como assinar eventos do Object Storage usando a CLI do IBM Cloud® Code Engine.

Muitas vezes, em ambientes distribuídos, você deseja que os seus aplicativos ou tarefas reajam a mensagens (eventos) que são geradas por meio de outros componentes, que geralmente são chamados de produtores de evento. Com o Code Engine, seus aplicativos ou tarefas podem receber eventos de interesse assinando os produtores de evento. As informações do evento são recebidas como solicitações de HTTP POST para aplicativos e como variáveis de ambiente para tarefas.

Antes de Iniciar

Todos os usuários do Code Engine são obrigados a ter uma conta pré-paga. Os tutoriais podem gerar custos adicionais. Use o Estimador de custos para gerar uma estimativa de custo com base em seu uso planejado. Para obter mais informações, consulte os preços do Code Engine.

Determinar seu depósito e sua região do Object Storage

O produtor de evento do Object Storage gera eventos com base em operações em objetos em depósitos do IBM Cloud Object Storage.

  1. Instale a CLI do plug-in Object Storage.

    ibmcloud plugin install cloud-object-storage

  2. Crie uma instância de recurso do Object Storage. Por exemplo, crie um recurso do Object Storage denominado mycloud-object-storage que usa o plano de serviço IBM Cloud Lite.

    ibmcloud resource service-instance-create mycloud-object-storage cloud-object-storage lite global

  3. Exiba os detalhes da instância do recurso do Object Storage que você criou. Use os detalhes para obter o CRN (Cloud Resource Name) a partir de sua instância do Object Storage. O CRN identifica qual instância do Object Storage você deseja usar. O CRN é o valor do campo ID na saída do comando ibmcloud resource service-instance COS_INSTANCE_NAME.

    ibmcloud resource service-instance mycloud-object-storage

    Saída de exemplo

    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
[...]

    Se você não souber o nome de sua instância do Object Storage, execute ibmcloud resource service-instances --service-name cloud-object-storage para ver uma lista de instâncias do Object Storage.

    Para obter mais informações sobre instâncias do Object Storage, consulte Introdução ao IBM Cloud Object Storage.

  4. Configure seu CRN do Object Storage que você localizou na etapa anterior para especificar uma instância do Object Storage com a qual trabalhar. Certifique-se de copiar o ID inteiro, começando com crn:. Este exemplos usa a opção --force para forçar a configuração a usar o CRN especificado, o que pode ser útil se você tiver mais de uma instância do Object Storage.

    ibmcloud cos config crn --crn CRN --force

    Saída de exemplo

    Saving new Service Instance ID...
OK
Successfully stored your service instance ID.

  5. Identifique um depósito para assinar. Para ver uma lista de depósitos que estão associados à sua instância do Object Storage,

    ibmcloud cos buckets

    Para criar um depósito,

    ibmcloud cos bucket-create -bucket BUCKET_NAME

  6. Identifique a localização e o plano do depósito do Object Storage; por exemplo, use o depósito mybucket.

    ibmcloud cos bucket-location-get --bucket mybucket

    Saída de exemplo

    Details about bucket mybucket:
Region: us-south
Class: Standard

O seu depósito do Object Storage deve ser um depósito regional localizado na mesma região de seu projeto Code Engine.

Atribuindo a função de Gerenciador de notificações ao Code Engine

Antes de criar uma assinatura do Object Storage, deve-se atribuir a função de Gerenciador de notificações a um projeto do Code Engine. Como um Gerenciador de notificações, o Code Engine pode visualizar, modificar e excluir notificações para um depósito do Object Storage.

Somente administradores de conta podem designar a função Gerenciador de Notificações.

  1. Identifique o projeto Code Engine que você deseja utilizar. É possível usar o comando ibmcloud ce project list para exibir uma lista de projetos. Use o comando ibmcloud ce project select para selecionar seu projeto como o contexto atual. Por exemplo, para selecionar um projeto denominado myproject

    ibmcloud ce project select -n myproject

  2. Atribua a função de Gerenciador de notificações usando o comando ibmcloud iam authorization-policy-create.

    Por exemplo, para atribuir a função de Gerenciador de Notificações a um projeto denominado myproject para uma instância do Object Storage denominada mycosinstance,

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

    Depois de designar a função de Gerenciador de Notificações para o seu projeto, é possível, então, criar assinaturas do Object Storage para quaisquer depósitos regionais em sua instância do Object Storage que estão na mesma região que o seu projeto.

    A tabela a seguir resume as opções que são usadas com o comando iam authorization-policy-create neste exemplo. Para obter mais informações sobre o comando e suas opções, consulte o comando ibmcloud iam authorization-policy-create.

    Componentes do comando iam authorization-policy-create
    Opção de comando Descrição
    codeengine O serviço de origem que pode ser autorizado a acessar.
    cloud-object-storage O serviço de destino que o serviço de origem pode ser autorizado a acessar.
    Notifications Manager As funções que fornecem acesso para o serviço de origem.
    source-service-instance-name O nome do projeto codeengine que você deseja autorizar para acesso.
    target-service-instance-name O nome da instância cloud-object-storage que você deseja acessar.

  3. Verifique se a função de Gerenciador de notificações está configurada.

    ibmcloud iam authorization-policies

    Saída de exemplo

    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

Crie seu app (ou tarefa)

Enquanto os eventos podem ser usados para acionar apps ou tarefas, este tutorial usa um app.

Crie um aplicativo denominado cos-app com o comando ibmcloud ce app create usando uma imagem chamada cos-listen. Esse app registra cada evento à medida que ele chega. Esta imagem foi criada a partir de cos-listen.go, disponível no repositório “Samples for IBM Cloud Code Engine ” GitHub.

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

Execute ibmcloud ce application get --name cos-app para verificar se o seu app está em um estado Ready. O aplicativo estará em um estado pronto se o resumo do status refletir que o aplicativo foi implementado com sucesso.

Para obter mais informações sobre este aplicativo, consulte o arquivo “readme” em IBM Cloud Object Storage.

Criar uma assinatura

Depois que o seu app estiver pronto, será possível criar uma assinatura do Object Storage para que você possa começar a receber eventos do Object Storage com o comando ibmcloud ce sub cos create.

Por exemplo, crie uma assinatura do Object Storage chamada de cos-sub. Esta assinatura encaminha qualquer tipo de operação de depósito a partir do depósito mybucket para um aplicativo que é chamado de cos-app.

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

Execute o comando ibmcloud ce sub cos get -n cos-sub para localizar informações sobre sua assinatura.

Saída de exemplo

Por padrão, o comando ibmcloud ce sub cos get retorna duas partes. A primeira parte inclui informações relacionadas à assinatura do Object Storage, como nome da assinatura, destino, prefixo, sufixo e tipo de evento. A segunda parte inclui informações de evento relacionadas a recursos sobre a assinatura do Object Storage que pode ser usada para propósitos de depuração. Por padrão, as informações do evento ficam disponíveis por 1 hora após a ocorrência.

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

Por padrão, o comando subscription cos create verifica primeiro se o aplicativo de destino existe. Se a verificação de destino falhar porque o nome do app que você forneceu não existe em seu projeto, o comando subscription cos create retornará um erro. Para criar uma assinatura sem primeiro criar o aplicativo, use a opção --force. Ao usar a opção --force, o comando ignora a verificação de destino. Observe que o campo Ready da assinatura mostra false até que o app de destino seja criado. Em seguida, a assinatura muda para um estado Ready: true automaticamente.

Após a criação da assinatura, mas antes que o comando subscription cos create relate quaisquer resultados, o comando subscription cos create pesquisa repetidamente a assinatura em busca de seu status para verificar sua prontidão. Essa pesquisa contínua de status dura 15 segundos por padrão antes de atingir o tempo limite. Se o status da assinatura retornar como Ready:true, ele relatará o sucesso, caso contrário, relatará um erro. É possível mudar a quantidade de tempo que o comando subscription cos create espera antes de atingir o tempo limite usando a opção --wait-timeout. Também é possível ignorar a pesquisa de status, configurando a opção --no-wait para false.

Para obter mais informações sobre cabeçalhos e corpo, consulte Cabeçalhos HTTP e informações do corpo para eventos.

Observe que as assinaturas podem afetar como um aplicativo é escalado. Para obter mais informações, consulte Configurando o ajuste de escala do aplicativo.

Testando a sua assinatura

  1. Faça upload de um arquivo .txt para o seu depósito. Por exemplo, é possível usar o comando ibmcloud cos object-put para fazer o upload do objeto sample.txt para um depósito com sample como o valor para --key.

    ibmcloud cos object-put --bucket mybucket --key sample --body sample.txt

  2. Visualize o evento processado usando o comando ibmcloud ce app logs.

    ibmcloud ce app logs --name cos-app

    Saída de exemplo

    Este comando retorna arquivos de log que incluem informações sobre o evento que foi encaminhado para seu app de destino. Na saída a seguir, é possível ver que uma operação de Write foi executada no objeto de sample no intervalo denominado 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"}

Atualizar sua assinatura do Object Storage

Agora que você sabe que sua assinatura de Object Storage foi criada com sucesso e que a assinatura de Object Storage está pronta para servir eventos, é possível atualizar a assinatura de Object Storage com o comando ibmcloud ce sub cos update. Por exemplo, é possível mudar sua assinatura para executar somente quando operações específicas ocorrerem em um subconjunto de objetos no depósito.

  1. Atualize a assinatura do Object Storage para encaminhar eventos somente quando operações delete ocorrerem em arquivos com um prefixo de nome de test.

    ibmcloud ce sub cos update --name cos-sub --event-type delete --prefix test

  2. Execute o comando ibmcloud ce sub cos get para localizar informações sobre a sua assinatura.

    ibmcloud ce sub cos get --name cos-sub

    Saída de exemplo

    Nesta saída, é possível ver que os valores atualizados para Prefix e EventType são exibidos.

    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

  3. Exclua um objeto do seu depósito que tenha o prefixo test. Por exemplo, exclua um arquivo com test2.txt como o nome (ou chave). É possível usar o comando ibmcloud cos object-delete para excluir um objeto de seu depósito ou usar o console do Object Storage.

  4. Visualize o evento processado usando o comando ibmcloud ce app logs.

    ibmcloud ce app logs --name cos-app

    Saída de exemplo

    Este comando retorna arquivos de log que incluem informações sobre o evento que foi encaminhado para seu app de destino. Na saída a seguir, é possível ver que uma operação de Delete foi executada no objeto de .txt no intervalo denominado 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"}

Tutorial de limpeza do Object Storage

Pronto para excluir sua assinatura do Object Storage e seu app? É possível usar os comandos ibmcloud ce app delete e ibmcloud ce sub cos delete.

Para remover a sua assinatura,

ibmcloud ce sub cos delete --name cos-sub

Para remover o seu aplicativo,

ibmcloud ce app delete --name cos-app

Pronto para excluir seu depósito e instância de serviço Object Storage? É possível usar o comando ibmcloud cos bucket-delete para remover seu depósito. Para remover sua instância de serviço do Object Storage, use o comando ibmcloud resource service-instance-delete.