Requisitos previos de la CLI

Antes de utilizar la CLI para gestionar destinos, lleve a cabo los pasos siguientes:

1. Instale la CLI de IBM Cloud.

2. Instale la CLI de IBM Cloud Activity Tracker Event Routing.

   Se requiere la CLI de « atracker » ( 0.3.2 ) o una versión superior para ejecutar comandos de la CLI de « Event Streams ». Si ha instalado previamente la CLI de atracker, es posible que tenga que actualizar el plugin de CLI de atracker ejecutando ibmcloud plugin update atracker.

3. Inicie sesión en IBM Cloud. Ejecute el siguiente mandato: ibmcloud login

Configuración de la autorización de « S2S » mediante la interfaz de usuario dentro de la misma cuenta

Realice lo siguiente para configurar una autorización de servicio a servicio utilizando la interfaz de usuario de IBM Cloud.

1. Inicie sesión en la cuenta de IBM Cloud como propietario de la cuenta que va a configurar los destinos de IBM Cloud Activity Tracker Event Routing.

   Después de iniciar sesión con su ID de usuario y su contraseña, se abre el panel de control de IBM Cloud.

2. Haz clic en «Gestionar» > Acceso (IAM). Aparece la pantalla « Gestionar acceso y usuarios ».

3. Pulse Autorizaciones.

4. Pulse Crear.

5. En « Servicio de origen », selecciona Activity Tracker y, en «¿Cómo desea delimitar el acceso?», seleccione «Todos los recursos ».

6. En «Servicio de destino», selecciona Message Hub en «¿Cómo desea delimitar el acceso?», seleccione «Recursos basados en los atributos seleccionados ».

7. Selecciona « Instancia de servicio » y escribe el nombre de tu instancia de Event Streams.

8. Para acceder al servicio, selecciona « Writer ».

9. Pulse Autorizar. La nueva autorización de servicio a servicio se especificará en la vista Gestionar autorizaciones.

Configuración de la autorización de « S2S » mediante la CLI

Realice lo siguiente para configurar una autorización de servicio a servicio utilizando la CLI de IBM Cloud.

1. Inicia sesión en tu cuenta de IBM Cloud como el titular de la cuenta que va a configurar la autorización de IBM Cloud Activity Tracker Event Routing.

2. Cree una política de autorización que defina la autorización de servicio a servicio.

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

   Donde:

   IES_SERVICE_INSTANCE es el CRN de la instancia Event Streams que se va a autorizar.

Configuración de la autorización de « S2S » mediante la API

Realice lo siguiente para configurar una autorización de servicio a servicio utilizando la API de IBM Cloud.

1. Inicie la sesión en la cuenta de IBM Cloud como propietario de la cuenta que va a configurar la autorización de IAM de IBM Cloud Activity Tracker Event Routing.

2. Cree un archivo authorization_policy_resource.json que defina la autorización de servicio a servicio.

   {
       "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"
                   }
               ]
           }
       ]
   }
   

   Donde:

   CUSTOMER_ACCOUNT_ID es el GUID de cuenta para la cuenta que va a configurar destinos. Esto se puede encontrar utilizando el mandato ibmcloud account list.

   IES_SERVICE_INSTANCE es el CRN de la instancia IES que se va a autorizar.

3. Obtenga una señal de acceso IAM. Para obtener más información, consulte Recuperación de señales de acceso de IAM.

4. Ejecute el mandato siguiente para configurar la autorización de servicio a servicio:

   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"
   

Creación de un destino de Event Streams utilizando la CLI

Utiliza este comando para crear un destino « IBM® Event Streams for IBM Cloud® » que se utilizará para configurar un destino para los eventos de actividad.

 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

Actualización de un destino de Event Streams utilizando la CLI

Utiliza este comando para actualizar un destino de Event Streams para una región de IBM Cloud Activity Tracker Event Routing. Cualquier valor especificado que sea distinto de cuando se creó originalmente el destino se actualizará al valor especificado en el mandato.

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

Supresión de un destino utilizando la CLI

Utilice este mandato para suprimir un 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.

Validación de un destino utilizando la CLI

Utilice este mandato para validar que un destino se ha configurado correctamente para una región de 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

Obtención de información sobre un destino utilizando la CLI

Utilice este mandato para obtener información sobre un destino para una región de 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

Listado de todos los destinos de una región

Utilice este mandato para generar una lista de los destinos configurados para una región de 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 y acciones de la API

En la tabla siguiente se listan las acciones que puede ejecutar para gestionar destinos:

Puede utilizar puntos finales públicos y privados para gestionar destinos. Para obtener más información sobre la lista de ENDPOINTS que están disponibles, consulte Puntos finales.

• Puede gestionar destinos desde la red privada utilizando un punto final de API con el formato siguiente: https://private.REGION.atracker.cloud.ibm.com

• Puede gestionar destinos desde la red pública utilizando un punto final de API con el formato siguiente: https://REGION.atracker.cloud.ibm.com

• Puede inhabilitar los puntos finales públicos actualizando los valores de la cuenta. Para obtener más información, consulte Configuración de los valores de destino y región.

Para obtener más información sobre la API REST, consulte Destinos.

Requisitos previos de la API

Para realizar llamadas de API para gestionar destinos, complete los pasos siguientes:

1. Obtenga una señal de acceso IAM. Para obtener más información, consulte Recuperación de señales de acceso de IAM.
2. Identifique el punto final de API en la región en la que tiene previsto configurar o gestionar un destino. Para obtener más información, consulte Puntos finales.

Creación de un destino de Event Streams utilizando la API

Puedes utilizar el siguiente comando curl para crear un destino de « 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}
    }
  }'

Donde

• TARGET_NAME es el nombre del destino. La longitud máxima del nombre es de 256 caracteres.

  No incluya información de identificación personal en ningún nombre de recurso.

• TARGET_TYPE es el tipo del destino. Establezca el valor en event_streams para un destino de Event Streams.

• BROKER_LIST es la lista de Event Streams intermediarios (puntos finales).

• TOPIC_NAME es el nombre de un nombre de tema Event Streams donde se envían los sucesos.

• API_KEY es el valor de contraseña que se encuentra en la credencial de servicio Event Streams. Esta es la clave de API de IAM.

• service_to_service_enabled determina si IBM Cloud Activity Tracker Event Routing tiene habilitada la autenticación de servicio a servicio. Establezca esta bandera a true si el servicio a servicio está habilitado y no suministra un apikey.

En la respuesta, obtiene información sobre el destino como, por ejemplo, el id, que indica el GUID del destino y el crn, que indica el CRN del destino.

Actualización de un destino de Event Streams utilizando la API

Al actualizar un destino de « IBM® Event Streams for IBM Cloud® » ( Event Streams ), debes incluir la información del destino en la sección de datos de la solicitud.

• Debe pasar todos los campos.
• Actualice los campos que deben cambiarse.
• No puede cambiar el target_type de un destino una vez creado.

Puede utilizar el siguiente mandato cURL para actualizar un 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}
    }
  }'

Donde

• TARGET_ID es el ID del destino.

• TARGET_NAME es el nombre del destino. La longitud máxima del nombre es de 256 caracteres.

  No incluya información de identificación personal en ningún nombre de recurso.

• TARGET_TYPE es el tipo del destino. Establezca el valor en event_streams para un destino de Event Streams.

• BROKER_LIST es la lista de Event Streams intermediarios (puntos finales).

• TOPIC_NAME es el nombre de un tema de Event Streams donde se envían los sucesos.

• API_KEY es el valor de contraseña que se encuentra en la credencial de servicio Event Streams. Esta es la clave de API de IAM.

• service_to_service_enabled determina si IBM Cloud Activity Tracker Event Routing tiene habilitada la autenticación de servicio a servicio. Establezca esta bandera a true si el servicio a servicio está habilitado y no suministra un apikey.

Supresión de un destino utilizando la API

Puede utilizar el siguiente mandato de cURL para suprimir un destino:

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

Donde

• <ENDPOINT> es el punto final de la API en la región donde tiene previsto configurar o gestionar un destino. Para obtener más información, consulte Puntos finales.
• <TARGET_ID> es el ID del destino.

Por ejemplo, puede utilizar la siguiente solicitud de cURL para suprimir un destino en EE.UU. sur con el 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"

En la respuesta, obtendrá un resultado vacío si la supresión se ha realizado correctamente:

{}

Validación de un destino utilizando la API

Puede utilizar el mandato cURL siguiente para validar un destino comprobando las credenciales para escribir en el destino.

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

Donde

• <ENDPOINT> es el punto final de la API en la región donde tiene previsto configurar o gestionar un destino. Para obtener más información, consulte Puntos finales.
• <TARGET_ID> es el ID del destino.

Por ejemplo, puede utilizar la siguiente solicitud cURL para validar un destino en EE.UU. sur con el 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"

En la respuesta, encontrarás información en la sección « write_status », por ejemplo:

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

Visualización de un destino utilizando la API

Puede utilizar el siguiente mandato de cURL para ver los detalles de configuración de 1 destino:

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

Donde

• <ENDPOINT> es el punto final de la API en la región donde tiene previsto configurar o gestionar un destino. Para obtener más información, consulte Puntos finales.
• <TARGET_ID> es el ID del destino.

Por ejemplo, puede ejecutar la siguiente solicitud cURL para obtener información sobre un destino con el 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"

Los resultados mostrarán si el objetivo es COS ("target_type": "cloud_object_storage") o Event Streams ("target_type": "event_streams").

Listar todos los destinos utilizando la API

Puede utilizar el siguiente mandato cURL para ver todos los destinos:

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

Donde

• <ENDPOINT> es el punto final de la API en la región donde tiene previsto configurar o gestionar un destino. Para obtener más información, consulte Puntos finales.

Por ejemplo, puede ejecutar la siguiente solicitud cURL para obtener información sobre los destinos definidos en Dallas:

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

Los resultados mostrarán si el objetivo es COS ("target_type": "cloud_object_storage") o Event Streams ("target_type": "event_streams").

Códigos de respuesta de HTTP

Cuando se utiliza la API REST de IBM Cloud Activity Tracker Event Routing, es posible obtener códigos de respuesta HTTP estándar para indicar si un método se ha completado satisfactoriamente.

• Una respuesta de 200 siempre indica éxito.
• Una respuesta 4xx indica una anomalía.
• Una respuesta 5xx normalmente indica un error interno del sistema.

Consulte la tabla siguiente para ver algunos códigos de respuesta HTTP:

Creación de un destino de Event Streams utilizando la interfaz de usuario

Sólo se listan y se pueden seleccionar los recursos de su cuenta. Para especificar un recurso en una cuenta diferente, seleccione Especificar CRN en Seleccionar destino.

1. Inicie sesión en su cuenta de IBM Cloud.
2. Haz clic en el icono de menú > Observabilidad.
3. Selecciona « Seguimiento de la actividad »...
4. Pulse Crear para abrir el panel de creación.
5. Elegir tipo: pulse Event Streams.
6. Elegir destino: seleccione Buscar por instancia o Especificar CRN
   • Buscar por instancia: Seleccione una instancia de Event Streams en la tabla o pulse Crear para crear una nueva instancia de Event Streams.
   • Especificar CRN: especifique el nombre de recurso de nube (CRN) de la instancia de Event Streams. Esto le permite especificar un CRN desde una cuenta diferente.

• Credenciales de servicio: Seleccione una de las credenciales de servicio, contiene el nombre de usuario de lista de intermediarios y api_key o contraseña.
• TemaEvent Streams: Seleccione un tema existente.
• Nombre de destino: especifique un nombre significativo para el destino.
• Región de destino: seleccione la región que procesará los datos de suceso.
• Conmute Establecer como destino predeterminado para establecer automáticamente el nuevo destino como destino predeterminado en los valores de IBM Cloud Activity Tracker Event Routing. Consulte la documentación de destinos predeterminados para obtener más detalles.
• Pulse Crear destino.

Actualización de un destino de Event Streams utilizando la interfaz de usuario

Sólo se listan y se pueden seleccionar los recursos de su cuenta. Para especificar un recurso en una cuenta diferente, seleccione Especificar CRN en Seleccionar destino.

1. Inicie sesión en su cuenta de IBM Cloud.
2. Haz clic en el icono de menú > Observabilidad.
3. Selecciona « Seguimiento de la actividad ».
4. Selecciona el elemento que deseas actualizar y haz clic en el .
5. Puede pulsar No establecer como valor predeterminado para eliminar el destino como destino predeterminado en los valores de IBM Cloud Activity Tracker Event Routing. Consulte la documentación de destinos predeterminados para obtener más detalles.
6. Pulse Editar para abrir el panel de actualización.
7. Detalles: Pulse Editar para actualizar el nombre o la región del destino. También puede conmutar Destino predeterminado para añadir o eliminar el destino como destino predeterminado en los valores de IBM Cloud Activity Tracker Event Routing.
8. Pulse Guardar para actualizar el destino.
9. Destino: pulse Editar para cambiar la instancia, credencial de servicio o tema de Event Streams asociado con el destino.
10. Pulse Guardar para actualizar el destino.

Cómo eliminar un destino mediante la interfaz de usuario

No se puede eliminar un destino de « IBM Cloud Activity Tracker Event Routing » si se utiliza en una ruta o como configuración de destino por defecto.

1. Inicie sesión en su cuenta de IBM Cloud.
2. Haz clic en el icono de menú > Observabilidad.
3. Selecciona « Seguimiento de la actividad ».
4. Selecciona el elemento que deseas eliminar y haz clic en el .
5. Pulse Suprimir y, a continuación, pulse Suprimir en el panel de confirmación.

Mostrar todos los objetivos de una región mediante la interfaz de usuario

1. Inicie sesión en su cuenta de IBM Cloud.
2. Haz clic en el icono de menú > Observabilidad.
3. Selecciona « Seguimiento de la actividad ».

En la tabla se recogen todos los datos de los destinatarios:

• Tipo de destino
• Nombre de destino
• Región de destino
• Rutas: si se utiliza en alguna ruta
• Estado del objetivo:
  • Activo: el destino funciona según lo esperado
  • Error: el destino está mal configurado y los sucesos no se direccionarán al destino. Actualice los detalles de destino o el destino para arreglar la configuración de destino o suprima el destino si ya no es necesario