Pré-requisitos da CLI

Antes de usar a CLI para gerenciar destinos, conclua as seguintes etapas:

1. Instale a CLI da IBM Cloud.

2. Instale a CLI da IBM Cloud Activity Tracker Event Routing.

   É necessário o CLI do atracker 0.3.2 ou versão superior para executar os comandos do CLI do Event Streams. Se você tiver instalado anteriormente a CLI do atracker, poderá ser necessário fazer upgrade do atracker plug-in da CLI executando ibmcloud plugin update atracker.

3. Efetue login no IBM Cloud. Execute o comando a seguir: ibmcloud login

Configurando a autorização d S2S e por meio da interface do usuário dentro da mesma conta

Para configurar uma autorização de serviço a serviço usando a interface com o usuário IBM Cloud, faça conforme a seguir.

1. Efetue login na sua conta IBM Cloud como o proprietário da conta que estará configurando destinos IBM Cloud Activity Tracker Event Routing.

   Depois de efetuar login com seu ID do usuário e senha, o painel do IBM Cloud se abre.

2. Clique em Gerenciar > Acesso (IAM). É exibida a tela “Gerenciar acesso e usuários ”.

3. Clique em Autorizações.

4. Clique em Criar.

5. Para o serviço de origem, selecione Activity Tracker e, em “Como você deseja definir o escopo do acesso? ”, selecione “Todos os recursos ”.

6. Para o serviço de destino, selecione Message Hub em “Como você deseja definir o escopo do acesso? ”, selecione “Recursos com base nos atributos selecionados ”.

7. Selecione “Instância do serviço ” e a sequência de caracteres deve ser igual ao nome da sua instância do Event Streams.

8. Para acessar o serviço, selecione “Writer ”.

9. Clique em Autorizar. Sua nova autorização de serviço a serviço será listada na visualização Gerenciar autorizações.

Configurando a autorização d S2S por meio da CLI

Para configurar uma autorização de serviço a serviço usando a CLI IBM Cloud, faça conforme a seguir.

1. Faça login na sua conta do IBM Cloud como o titular da conta que irá configurar a autorização d IBM Cloud Activity Tracker Event Routing.

2. Crie uma política de autorização definindo sua autorização de serviço a serviço.

   ibmcloud iam authorization-policy-create atracker messagehub "Writer" [--target-service-instance-id <IES_SERVICE_INSTANCE>
   

   Em que:

   IES_SERVICE_INSTANCE é o CRN da instância do Event Streams a ser autorizada.

Configurando a autorização d S2S, utilizando a API

Para configurar uma autorização de serviço a serviço usando a API IBM Cloud, faça conforme a seguir.

1. Efetue login na sua conta IBM Cloud como o proprietário da conta que estará configurando autorização do IAM IBM Cloud Activity Tracker Event Routing

2. Crie um arquivo authorization_policy_resource.json definindo sua autorização de serviço para serviço.

   {
       "type": "authorization",
       "subjects": [
           {
               "attributes": [
                 {
                      "name": "accountId",
                      "value": "CUSTOMER_ACCOUNT_ID"
                  },
                  {
                       "name": "serviceName",
                       "value": "atracker"
                   }
               ]
           }
       ],
       "roles": [
           {
               "role_id": "crn:v1:bluemix:public:iam::::serviceRole:Writer"
           }
       ],
       "resources": [
           {
               "attributes": [
                 {
                      "name": "accountId",
                      "value": "CUSTOMER_ACCOUNT_ID"
                  },
                  {
                       "name": "serviceName",
                       "value": "messagehub"
                   },
                   {
                       "name": "serviceInstance",
                       "value": "IES_SERVICE_INSTANCE"
                   }
               ]
           }
       ]
   }
   

   Em que:

   CUSTOMER_ACCOUNT_ID é o GUID da conta para a conta que estará configurando destinos. Isso pode ser localizado usando o comando ibmcloud account list.

   IES_SERVICE_INSTANCE é o CRN da instância do IES a ser autorizada.

3. Obtenha um token de acesso do IAM. Para obter mais informações, consulte Recuperando tokens de acesso do iAM.

4. Execute o comando a seguir para configurar a sua autorização de serviço a serviço:

   curl -X POST --header 'Content-Type: application/json' --header 'Accept: application/json' --header "Authorization: $ACCESS_TOKEN" -d @authorization_policy_resource.json "https://iam.cloud.ibm.com/v1/policies"
   

Criando um destino Event Streams usando a CLI

Use este comando para criar um destino “ IBM® Event Streams for IBM Cloud® ” a ser utilizado na configuração de um destino para eventos de atividade.

 ibmcloud atracker target create --name TARGET_NAME --type TARGET_TYPE ( [--file EVENTSTREAMS_ENDPOINT_DEFINITION_JSON_FILE] | ( [--target-crn EVENTSTREAMS_TARGET_CRN] [--brokers BROKER_LIST] [--topic TOPIC] [--api-key ( EVENTSTREAMS_API_KEY | @EVENTSTREAMS_API_KEY_FILE )] | [--service-to-service-enabled ( TRUE | FALSE )]) ) [--region REGION] [--output FORMAT]

Target
Name:                     my-target
ID:                       000000000-00000000-0000-0000-00000000
CRN:                      crn:v1:staging:public:atracker:us-south:a/xxxxxxxxxx:xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxx
Region:                   us-south
Type:                     event_streams
Event Streams Target CRN: crn:v1:bluemix:public:messagehub:us-south:a/xxxxxxxxxx:xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxx::
Event Streams Topic:      my-topic
Event Streams Brokers:    [broker-1:9093,broker-2:9093]
Write Status:             success
CreatedAt:                2022-10-20T19:20:38.888Z
UpdatedAt:                2022-10-20T19:20:38.888Z

Atualizando um destino Event Streams usando a CLI

Use este comando para atualizar um destino do Event Streams para uma região do IBM Cloud Activity Tracker Event Routing. Qualquer valor especificado que seja diferente do momento da criação do destino será atualizado para o valor especificado no comando.

ibmcloud atracker target update --target TARGET [--name TARGET_NAME] [ [--file EVENTSTREAMS_ENDPOINT_DEFINITION_JSON_FILE] | ( [--brokers BROKER_LIST] [--target-crn EVENTSTREAMS_TARGET_CRN] [--topic TOPIC] ( [--api-key ( EVENTSTREAMS_API_KEY | @EVENTSTREAMS_API_KEY_FILE )] | [--service-to-service-enabled ( TRUE | FALSE )]))] [--output FORMAT]

Target
Name:                     my-new-target
ID:                       000000000-00000000-0000-0000-00000000
CRN:                      crn:v1:staging:public:atracker:us-south:a/xxxxxxxxxx:xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxx
Region:                   us-south
Type:                     event_streams
Event Streams Target CRN: crn:v1:bluemix:public:messagehub:us-south:a/xxxxxxxxxx:xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxx::
Event Streams Topic:      my-topic
Event Streams Brokers:    [broker-1:9093,broker-2:9093]
Write Status:             success
CreatedAt:                2022-10-20T19:20:38.888Z
UpdatedAt:                2022-10-20T19:20:38.888Z

Excluindo um destino usando a CLI

Use este comando para excluir um destino.

ibmcloud atracker target rm --target TARGET [--force]

Are you sure you want to remove the target with target ID xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx? [y/N]>y
OK
Target with target ID xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx was successfully removed.

Are you sure you want to remove the Target bearing Target ID 33333333-3333-3333-3333-333333333333? [y/N]> y
FAILED
Something went wrong. Error:
 Status Code:  404
 Incident ID:  67a33257-d5a4-46ec-94d9-14eb70e94f3d
 Code:         not_found
 Message:      The target id specified in `target_id` field is not found.

Validando um destino usando a CLI

Use esse comando para validar que um destino foi configurado corretamente para uma região do IBM Cloud Activity Tracker Event Routing.

ibmcloud atracker target validate --target TARGET [--region REGION] [--output FORMAT]

Target
Name:               		    new-target-name
ID:                 		    xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
CRN:               		      crn:v1:staging:public:atracker:us-south:a/xxxxxxxxxx:xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxx
Region:                     us-south
Type:                       event_streams
Event Streams Target CRN:   crn:v1:bluemix:public:messagehub:us-south:a/a/xxxxxxxxxx:xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxx::
Event Streams Topic:        my-test-topic
Event Streams Brokers:      [broker-1:9093,broker-2:9093]
Write Status:               success
CreatedAt:                  2022-10-20T19:20:38.888Z
UpdatedAt:                  2022-10-20T19:20:38.888Z

Obtendo informações sobre um destino que usa a CLI

Use esse comando para obter informações sobre um destino para uma região do IBM Cloud Activity Tracker Event Routing.

ibmcloud atracker target get --target TARGET [--output FORMAT]

Target
Name:               		    updated-target-name
ID:                 		    xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
CRN:               		      crn:v1:staging:public:atracker:us-south:a/xxxxxxxxxx:xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxx
Region:                     us-south
Type:                       event_streams
Event Streams Target CRN:   crn:v1:bluemix:public:messagehub:us-south:a/a/xxxxxxxxxx:xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxx::
Event Streams Topic:        my-test-topic
Event Streams Brokers:      [broker-1:9093,broker-2:9093]
Write Status:               success
CreatedAt:                  2022-10-20T19:20:38.888Z
UpdatedAt:                  2022-10-20T19:20:38.888Z

Listando todos os destinos em uma região

Use esse comando para listar os destinos configurados para uma região do IBM Cloud Activity Tracker Event Routing.

ibmcloud atracker target ls [--output FORMAT]

Name                       ID                                     Region     Type             Service to Service Enabled Created
target-01                  xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx   us-south    event_streams   -				                     2020-11-18T03:52:08.603Z
target-02                  yyyyyyyy-yyyy-yyyy-yyyy-yyyyyyyyyyyy   us-south    event_streams   -				                     2020-11-18T03:52:01.592Z
target-02-backup           zzzzzzzz-zzzz-zzzz-zzzz-zzzzzzzzzzzz   us-east     event_streams   -				                     2021-02-26T06:53:13.466Z

Destinos e ações da API

A tabela a seguir lista as ações que podem ser executadas para gerenciar destinos:

É possível usar terminais privados e públicos para gerenciar destinos. Para obter mais informações sobre a lista de ENDPOINTS disponíveis, consulte Terminais.

• É possível gerenciar destinos a partir da rede privada usando um terminal de API com o formato a seguir: https://private.REGION.atracker.cloud.ibm.com

• É possível gerenciar destinos a partir da rede pública usando um terminal de API com o formato a seguir: https://REGION.atracker.cloud.ibm.com

• É possível desativar os terminais públicos atualizando as configurações da conta. Para obter informações adicionais, consulte Definindo configurações de destino e região.

Para obter mais informações sobre a API de REST, consulte Destinos.

Pré-requisitos da API

Para fazer chamadas de API para gerenciar destinos, conclua as seguintes etapas:

1. Obtenha um token de acesso do IAM. Para obter mais informações, consulte Recuperando tokens de acesso do iAM.
2. Identifique o terminal da API na região em que você planeja configurar ou gerenciar um destino. Para obter mais informações, consulte Terminais.

Criando um destino Event Streams usando a API

Você pode usar o seguinte comando do curl para criar um destino do IBM® Event Streams for IBM Cloud® ( Event Streams ):

curl -X POST  <ENDPOINT>/api/v2/targets   -H "Authorization:  $ACCESS_TOKEN"   -H "content-type: application/json"   -d '{
    "name": "TARGET_NAME",
    "target_type": "TARGET_TYPE",
    "eventstreams_endpoint": {
        "target_crn": "EVENTSTREAMS_CRN",
        "brokers": "BROKER_LIST",
        "topic”: "TOPIC_NAME",
        "password": "API_KEY",
        "service_to_service_enabled": false}
    }
  }'

em que

• TARGET_NAME é o nome do destino. O comprimento máximo do nome é de 256 caracteres.

  Não inclua nenhuma PII (Personal Identifying Information) em quaisquer nomes de recursos.

• TARGET_TYPE é o tipo do destino. Configure o valor como event_streams para um destino Event Streams.

• BROKER_LIST é a lista de brokers do Event Streams (terminais).

• TOPIC_NAME é o nome de um nome de tópico do Event Streams no qual os eventos são enviados.

• API_KEY é o valor da senha localizado na credencial de serviço Event Streams. Esta é a chave de API do IAM

• service_to_service_enabled determina se IBM Cloud Activity Tracker Event Routing tem a autenticação de serviço para serviço ativada. Defina esse sinalizador como true se a opção service to service estiver ativada e não fornecer uma apikey.

Na resposta, são fornecidas informações sobre o destino como o id, que indica o GUID do destino, e o crn, que indica o CRN do destino.

Atualizando um destino Event Streams usando a API

Ao atualizar um destino do IBM® Event Streams for IBM Cloud® ( Event Streams ), é necessário incluir as informações do destino na seção de dados da solicitação.

• Deve-se ter aprovação em todos os campos.
• Atualize os campos que precisam ser modificados.
• Uma vez criado, não é possível mudar o target_type de um destino.

É possível usar o comando cURL a seguir para atualizar um destino:

curl -X PUT  <ENDPOINT>/api/v2/targets/TARGET_ID  -H "Authorization:  $ACCESS_TOKEN"   -H "content-type: application/json"   -d '{
    "name": "TARGET_NAME",
    "target_type": "TARGET_TYPE",
    "eventstreams_endpoint": {
      "target_crn": "EVENTSTREAMS_CRN",
      "brokers": "BROKER_LIST",
      "topic”: "TOPIC_NAME",
      "password": "API_KEY",
      "service_to_service_enabled": false}
    }
  }'

em que

• TARGET_ID é o ID do destino.

• TARGET_NAME é o nome do destino. O comprimento máximo do nome é de 256 caracteres.

  Não inclua nenhuma PII (Personal Identifying Information) em quaisquer nomes de recursos.

• TARGET_TYPE é o tipo do destino. Configure o valor como event_streams para um destino Event Streams.

• BROKER_LIST é a lista de brokers do Event Streams (terminais).

• TOPIC_NAME é o nome de um tópico Event Streams no qual os eventos são enviados.

• API_KEY é o valor da senha localizado na credencial de serviço Event Streams. Esta é a chave de API do IAM

• service_to_service_enabled determina se IBM Cloud Activity Tracker Event Routing tem a autenticação de serviço para serviço ativada. Defina esse sinalizador como true se a opção service to service estiver ativada e não fornecer uma apikey.

Excluindo um destino que usa a CLI

É possível usar o comando cURL a seguir para excluir um destino:

curl -X DELETE <ENDPOINT>/api/v2/targets/<TARGET_ID> -H "Authorization:  $ACCESS_TOKEN" -H "content-type: application/json"

em que

• <ENDPOINT> é o terminal de API na região em que você planeja configurar ou gerenciar um destino. Para obter mais informações, consulte Terminais.
• <TARGET_ID> é o ID do destino.

Por exemplo, pode-se usar a solicitação cURL a seguir para excluir um destino na região US-South com o ID 00000000-0000-0000-0000-000000000000:

curl -X DELETE https://private.us-south.atracker.cloud.ibm.com/api/v2/targets/00000000-0000-0000-0000-000000000000 -H "Authorization: $ACCESS_TOKEN" -H "content-type: application/json"

Na resposta, obtém-se um resultado vazio se a exclusão foi bem-sucedida:

{}

Validando um destino que usa a API

É possível usar o comando cURL a seguir para validar um destino, verificando as credenciais para gravar no destino.

curl -X POST <ENDPOINT>/api/v2/targets/<TARGET_ID>/validate -H "Authorization: $ACCESS_TOKEN" -H "content-type: application/json"

em que

• <ENDPOINT> é o terminal de API na região em que você planeja configurar ou gerenciar um destino. Para obter mais informações, consulte Terminais.
• <TARGET_ID> é o ID do destino.

Por exemplo, é possível usar a solicitação cURL a seguir para validar um destino na região US-South com o ID 00000000-0000-0000-0000-000000000000:

curl -X POST https://private.us-south.atracker.cloud.ibm.com/api/v2/targets/<TARGETID>/validate -H "Authorization: $ACCESS_TOKEN" -H "content-type: application/json"

Na resposta, você encontra informações na seção write_status, por exemplo:

"write_status": {
    "status": "success"
  },

Visualizando um destino que usa a API

É possível usar o comando cURL a seguir para visualizar os detalhes de configuração de um destino:

curl -X GET <ENDPOINT>/api/v2/targets/<TARGET_ID> -H "Authorization: $ACCESS_TOKEN" -H "content-type: application/json"

em que

• <ENDPOINT> é o terminal de API na região em que você planeja configurar ou gerenciar um destino. Para obter mais informações, consulte Terminais.
• <TARGET_ID> é o ID do destino.

Por exemplo, pode-se executar a solicitação cURL a seguir para obter informações sobre um destino com o ID 00000000-0000-0000-0000-000000000000:

curl -X GET https://private.us-south.atracker.cloud.ibm.com/api/v2/targets/00000000-0000-0000-0000-000000000000 -H "Authorization: $ACCESS_TOKEN" -H "content-type: application/json"

Os resultados mostrarão se o alvo é COS ("target_type": "cloud_object_storage") ou Event Streams ("target_type": "event_streams").

Listando todos os destinos usando a API

É possível usar o comando cURL a seguir para visualizar todos os destinos:

curl -X GET <ENDPOINT>/api/v2/targets -H "Authorization: $ACCESS_TOKEN" -H "content-type: application/json"

em que

• <ENDPOINT> é o terminal de API na região em que você planeja configurar ou gerenciar um destino. Para obter mais informações, consulte Terminais.

Por exemplo, pode-se executar a solicitação cURL a seguir para obter informações sobre os destinos que são definidos em Dallas:

curl -X GET https://private.us-south.atracker.cloud.ibm.com/api/v2/targets -H "Authorization:  $ACCESS_TOKEN" -H "content-type: application/json"

Os resultados mostrarão se o alvo é COS ("target_type": "cloud_object_storage") ou Event Streams ("target_type": "event_streams").

Códigos de resposta HTTP

Quando você usa a API de REST do IBM Cloud Activity Tracker Event Routing, pode obter códigos de resposta HTTP padrão para indicar se um método foi concluído com sucesso.

• A resposta 200 sempre indica sucesso.
• A resposta 4xx indica uma falha.
• A resposta 5xx geralmente indica um erro no sistema interno.

Consulte a tabela a seguir para obter alguns códigos de resposta HTTP:

Criando um destino Event Streams usando a IU

Somente os recursos em sua conta são listados e selecionáveis Para especificar um recurso em uma conta diferente, selecione Especificar CRN em Escolher destino..

1. Efetue login na conta do IBM Cloud.
2. Clique no ícone do menu > Observabilidade.
3. Selecione “Acompanhamento de atividades ”...
4. Clique em Criar para abrir o painel de criação
5. Escolher tipo: clique em Event Streams.
6. Escolher destino: selecione Procurar por instância ou Especificar CRN
   • Procurar por instância: selecione uma instância Event Streams na tabela ou clique em Criar para criar uma nova instância Event Streams.
   • Especificar CRN: insira o Cloud Resource Name (CRN) da instância do Event Streams. Isso permite que você insira um CRN de uma conta diferente.

• Credenciais de serviço: selecione uma das credenciais de serviço, que contém o nome do usuário da lista de brokers e api_key ou senha.
• Event Streams: Selecione um tópico existente.
• Nome de destino: Insira um nome significativo no destino.
• Região de destino: selecione a região que processará os dados do evento..
• Alterne Configurar como destino padrão para configurar automaticamente seu novo destino como um destino padrão nas configurações do IBM Cloud Activity Tracker Event Routing. Consulte a documentação de destinos padrão para obter mais detalhes..
• Clique em Criar destino..

Atualizando um destino Event Streams usando a IU

Somente os recursos em sua conta são listados e selecionáveis Para especificar um recurso em uma conta diferente, selecione Especificar CRN em Escolher destino..

1. Efetue login na conta do IBM Cloud.
2. Clique no ícone do menu > Observabilidade.
3. Selecione “Acompanhamento de atividades ”.
4. Selecione o destino a ser atualizado e clique no .
5. É possível clicar em Desconfigurar como padrão para remover seu destino como um destino padrão em suas configurações do IBM Cloud Activity Tracker Event Routing Consulte a Documentação de destinos padrão para obter mais detalhes
6. Clique em Editar para abrir o painel de atualização
7. Detalhes: clique em Editar para atualizar o nome ou região de seu destino. Também é possível alternar Destino padrão para incluir ou remover seu destino como um destino padrão nas configurações do IBM Cloud Activity Tracker Event Routing.
8. Clique em Salvar para atualizar seu destino..
9. Destino: Clique em Editar para mudar a instância do Event Streams, a credencial de serviço ou o tópico associado ao seu destino.
10. Clique em Salvar para atualizar seu destino..

Excluindo um destino usando a interface do usuário

Não é possível excluir um destino do tipo “ IBM Cloud Activity Tracker Event Routing ” se ele for utilizado em uma rota ou como configuração de destino padrão.

1. Efetue login na conta do IBM Cloud.
2. Clique no ícone do menu > Observabilidade.
3. Selecione “Acompanhamento de atividades ”.
4. Selecione o item a ser excluído e clique no .
5. Clique em Excluir e, em seguida, clique em Excluir no painel de confirmação.

Listar todos os alvos em uma região usando a interface do usuário

1. Efetue login na conta do IBM Cloud.
2. Clique no ícone do menu > Observabilidade.
3. Selecione “Acompanhamento de atividades ”.

A tabela apresenta todos os detalhes dos alvos:

• Tipo de destino
• Nome do destino
• Região de destino
• Rotas: se for usado em quaisquer rotas
• Status da meta:
  • Ativo: O destino está funcionando conforme esperado
  • Erro: o destino está configurado incorretamente e os eventos não serão roteados para o destino. Atualize seus detalhes de destino ou destino para corrigir a configuração de destino ou exclua o destino se ele não for mais necessário