Prerequisiti CLI

Prima di utilizzare la CLI per gestire le destinazioni, completare i seguenti passaggi:

1. Installa la CLI IBM Cloud.

2. Installa la CLI IBM Cloud Activity Tracker Event Routing.

   Per eseguire i comandi della CLI di Event Streams è necessaria la versione 0.3.2 o successiva della CLI di atracker. Se hai già installato la CLI atracker, potrebbe essere necessario aggiornare il plug-in CLI atracker eseguendo ibmcloud plugin update atracker.

3. Accedi a IBM Cloud. Esegui il seguente comando: ibmcloud login

Configurazione dell'autorizzazione S2S tramite l'interfaccia utente all'interno dello stesso account

Per configurare un'autorizzazione da servizio a servizio utilizzando l'interfaccia utente di IBM Cloud procedere come segue.

1. Accedi al tuo account IBM Cloud come proprietario dell'account che configurerà i target IBM Cloud Activity Tracker Event Routing.

   Dopo che hai eseguito l'accesso con il tuo ID utente e la tua password, viene aperto il dashboard IBM Cloud.

2. Fai clic su Gestisci > Accesso (IAM). Viene visualizzata la schermata " Gestisci accessi e utenti ".

3. Fare clic su Autorizzazioni.

4. Fai clic su Crea.

5. Per il servizio Origine seleziona Activity Tracker e per Come desideri definire l'ambito dell'accesso? seleziona Tutte le risorse.

6. Per il servizio di destinazione seleziona Message Hub Per Come desideri definire l'ambito dell'accesso? seleziona Risorse in base agli attributi selezionati.

7. Seleziona l'istanza del servizio e la stringa è uguale al nome della tua istanza Event Streams.

8. Per accedere al servizio selezionare Writer.

9. Fai clic su Autorizza. La nuova autorizzazione da servizio a servizio verrà elencata nella vista Gestisci autorizzazioni.

Configurazione dell'autorizzazione S2S tramite CLI

Per configurare un'autorizzazione da servizio a servizio utilizzando la CLI IBM Cloud procedere come segue.

1. Accedi al tuo account IBM Cloud come proprietario dell'account che configurerà l'autorizzazione IBM Cloud Activity Tracker Event Routing.

2. Crea una policy di autorizzazione che definisca l'autorizzazione da servizio a servizio.

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

   Dove:

   IES_SERVICE_INSTANCE è il CRN dell'istanza di Event Streams da autorizzare.

Configurazione dell'autorizzazione S2S tramite API

Per configurare un'autorizzazione da servizio a servizio utilizzando l'API IBM Cloud, procedere come segue.

1. Accedi al tuo account IBM Cloud come proprietario dell'account che configurerà l'autorizzazione IAM IBM Cloud Activity Tracker Event Routing.

2. Crea un file authorization_policy_resource.json che definisca l'autorizzazione da servizio a servizio.

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

   Dove:

   CUSTOMER_ACCOUNT_ID è il GUID dell'account che configurerà i target. Per scoprirlo, utilizzare il comando ibmcloud account list.

   IES_SERVICE_INSTANCE è il CRN dell'istanza IES da autorizzare.

3. Ottenere un token di accesso IAM. Per ulteriori informazioni, vedere Recupero dei token di accesso IAM.

4. Eseguire il seguente comando per configurare l'autorizzazione da servizio a servizio:

   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"
   

Creazione di un target Event Streams tramite la CLI

Utilizzare questo comando per creare un target IBM® Event Streams for IBM Cloud® da utilizzare per configurare una destinazione per gli eventi di attività.

 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

Aggiornamento di un target Event Streams tramite la CLI

Utilizzare questo comando per aggiornare un target Event Streams per una regione IBM Cloud Activity Tracker Event Routing. Qualsiasi valore specificato diverso da quello impostato al momento della creazione originale della destinazione verrà aggiornato al valore specificato nel 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

Eliminazione di un target tramite CLI

Utilizza questo comando per eliminare una destinazione.

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.

Convalida di un target tramite CLI

Utilizzare questo comando per convalidare che un target sia configurato correttamente per una regione 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

Ottenere informazioni su un target utilizzando la CLI

Utilizzare questo comando per ottenere informazioni su un target per una regione 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

Elencare tutti gli obiettivi in una regione

Utilizzare questo comando per elencare le destinazioni configurate per una regione 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

Obiettivi e azioni API

La tabella seguente elenca le operazioni che è possibile eseguire per gestire le destinazioni:

È possibile utilizzare endpoint privati e pubblici per gestire i target. Per ulteriori informazioni sull'elenco dei ENDPOINTS disponibili, vedere Endpoint.

• È possibile gestire i target dalla rete privata utilizzando un endpoint API con il seguente formato: https://private.REGION.atracker.cloud.ibm.com

• È possibile gestire i target dalla rete pubblica utilizzando un endpoint API con il seguente formato: https://REGION.atracker.cloud.ibm.com

• È possibile disattivare gli endpoint pubblici aggiornando le impostazioni dell'account. Per ulteriori informazioni, vedere Configurazione delle impostazioni di destinazione e regione.

Per ulteriori informazioni sulla REST API, vedere Target.

Prerequisiti API

Per effettuare chiamate API per gestire le destinazioni, completare i seguenti passaggi:

1. Ottenere un token di accesso IAM. Per ulteriori informazioni, vedere Recupero dei token di accesso IAM.
2. Identifica l'endpoint API nella regione in cui intendi configurare o gestire una destinazione. Per ulteriori informazioni, vedere Endpoint.

Creazione di un target Event Streams tramite l'API

Puoi utilizzare il seguente comando curl per creare un target 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}
    }
  }'

Dove

• TARGET_NAME è il nome della destinazione. La lunghezza massima del nome è di 256 caratteri.

  Non includere alcuna informazione di identificazione personale (PII) nei nomi delle risorse.

• TARGET_TYPE è il tipo di destinazione. Imposta il valore su event_streams per un target Event Streams.

• BROKER_LIST è l'elenco dei broker (endpoint) Event Streams.

• TOPIC_NAME è il nome di un argomento Event Streams a cui vengono inviati gli eventi.

• API_KEY è il valore della password trovato nelle credenziali del servizio Event Streams. Questa è la chiave API IAM.

• service_to_service_enabled determina se IBM Cloud Activity Tracker Event Routing ha abilitata l'autenticazione da servizio a servizio. Impostare questo flag su true se il servizio al servizio è abilitato e non fornire una chiave API.

Nella risposta si ottengono informazioni sul target, come id, che indica il GUID del target, e crn, che indica il CRN del target.

Aggiornamento di un target Event Streams tramite API

Quando aggiorni un target IBM® Event Streams for IBM Cloud® ( Event Streams ), devi includere le informazioni sul target nella sezione dati della richiesta.

• Devi superare tutti i campi.
• Aggiorna i campi che devono essere modificati.
• Non è possibile modificare il target_type di un target una volta creato.

Per aggiornare un target è possibile utilizzare il seguente comando curl:

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}
    }
  }'

Dove

• TARGET_ID è l'ID della destinazione.

• TARGET_NAME è il nome della destinazione. La lunghezza massima del nome è di 256 caratteri.

  Non includere alcuna informazione di identificazione personale (PII) nei nomi delle risorse.

• TARGET_TYPE è il tipo di destinazione. Imposta il valore su event_streams per un target Event Streams.

• BROKER_LIST è l'elenco dei broker (endpoint) Event Streams.

• TOPIC_NAME è il nome di un argomento Event Streams in cui vengono inviati gli eventi.

• API_KEY è il valore della password trovato nelle credenziali del servizio Event Streams. Questa è la chiave API IAM.

• service_to_service_enabled determina se IBM Cloud Activity Tracker Event Routing ha abilitata l'autenticazione da servizio a servizio. Impostare questo flag su true se il servizio al servizio è abilitato e non fornire una chiave API.

Eliminazione di un target tramite API

Per eliminare un target è possibile utilizzare il seguente comando curl:

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

Dove

• <ENDPOINT> è l'endpoint API nella regione in cui intendi configurare o gestire un target. Per ulteriori informazioni, vedere Endpoint.
• <TARGET_ID> è l'ID della destinazione.

Ad esempio, puoi utilizzare la seguente richiesta curl per eliminare un target in US-South con 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"

Nella risposta, se l'eliminazione è riuscita, si ottiene un risultato vuoto:

{}

Convalida di un target tramite API

È possibile utilizzare il seguente comando curl per convalidare una destinazione verificando le credenziali per scrivere sulla destinazione.

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

Dove

• <ENDPOINT> è l'endpoint API nella regione in cui intendi configurare o gestire un target. Per ulteriori informazioni, vedere Endpoint.
• <TARGET_ID> è l'ID della destinazione.

Ad esempio, puoi utilizzare la seguente richiesta curl per convalidare un target in US-South con 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"

Nella risposta, si ottengono informazioni nella sezione write_status, ad esempio:

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

Visualizzazione di un target tramite API

È possibile utilizzare il seguente comando curl per visualizzare i dettagli di configurazione di 1 destinazione:

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

Dove

• <ENDPOINT> è l'endpoint API nella regione in cui intendi configurare o gestire un target. Per ulteriori informazioni, vedere Endpoint.
• <TARGET_ID> è l'ID della destinazione.

Ad esempio, è possibile eseguire la seguente richiesta cURL per ottenere informazioni su un target con 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"

I risultati mostreranno se il target è COS ("target_type": "cloud_object_storage") o Event Streams ("target_type": "event_streams").

Elencare tutti gli obiettivi utilizzando l'API

È possibile utilizzare il seguente comando curl per visualizzare tutti i target:

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

Dove

• <ENDPOINT> è l'endpoint API nella regione in cui intendi configurare o gestire un target. Per ulteriori informazioni, vedere Endpoint.

Ad esempio, è possibile eseguire la seguente richiesta curl per ottenere informazioni sui target definiti a Dallas:

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

I risultati mostreranno se il target è COS ("target_type": "cloud_object_storage") o Event Streams ("target_type": "event_streams").

Codici di risposta HTTP

Quando si utilizza l'API REST di IBM Cloud Activity Tracker Event Routing, è possibile ottenere i codici di risposta standard di HTTP per indicare se un metodo è stato completato con successo.

• Una risposta pari a 200 indica sempre successo.
• Una risposta 4xx indica un errore.
• Una risposta 5xx indica solitamente un errore interno del sistema.

Vedere la tabella seguente per alcuni codici di risposta di HTTP:

Creazione di un target Event Streams tramite l'interfaccia utente

Sono elencate e selezionabili solo le risorse presenti nel tuo account. Per specificare una risorsa in un account diverso, selezionare Specifica CRN in Scegli destinazione.

1. Accedi al tuo account IBM Cloud.
2. Fai clic sull' Menu > Osservabilità.
3. Seleziona " Monitoraggio attività "...
4. Fare clic su Crea per aprire il pannello di creazione.
5. Scegli il tipo: fai clic su Event Streams.
6. Scegli destinazione: seleziona Cerca per istanza o Specifica CRN
   • Cerca per istanza: seleziona un'istanza di Event Streams dalla tabella o fai clic su Crea per creare una nuova istanza Event Streams.
   • Specifica CRN: immetti il nome della risorsa cloud (CRN) dell'istanza di Event Streams. Ciò consente di immettere un CRN da un account diverso.

• Credenziali del servizio: seleziona una delle credenziali del servizio, che contiene il nome utente dell'elenco dei broker e l'api_key o la password.
• Argomento Event Streams: seleziona un argomento esistente.
• Nome destinazione: immettere un nome significativo per la destinazione.
• Regione di destinazione: seleziona la regione in cui verranno elaborati i dati dell'evento.
• Attiva Imposta come destinazione predefinita per impostare automaticamente la nuova destinazione come destinazione predefinita nelle impostazioni di IBM Cloud Activity Tracker Event Routing. Per maggiori dettagli, consultare la documentazione degli obiettivi predefiniti.
• Fare clic su Crea destinazione.

Aggiornamento di un target Event Streams tramite l'interfaccia utente

Sono elencate e selezionabili solo le risorse presenti nel tuo account. Per specificare una risorsa in un account diverso, selezionare Specifica CRN in Scegli destinazione.

1. Accedi al tuo account IBM Cloud.
2. Fai clic sull' Menu > Osservabilità.
3. Seleziona " Monitoraggio attività ".
4. Individuare l'elemento da aggiornare e fare clic .
5. Puoi fare clic su Non impostare come predefinito per rimuovere il tuo target come target predefinito nelle impostazioni di IBM Cloud Activity Tracker Event Routing. Per maggiori dettagli, consultare la documentazione sui target predefiniti.
6. Fare clic su Modifica per aprire il pannello di aggiornamento.
7. Dettagli: fai clic su Modifica per aggiornare il nome o la regione del tuo target. Puoi anche attivare l'opzione Destinazione predefinita per aggiungere o rimuovere la tua destinazione come destinazione predefinita nelle impostazioni di IBM Cloud Activity Tracker Event Routing.
8. Fai clic su Salva per aggiornare il tuo obiettivo.
9. Destinazione: fai clic su Modifica per modificare l'istanza di Event Streams, le credenziali del servizio o l'argomento associato alla tua destinazione.
10. Fai clic su Salva per aggiornare il tuo obiettivo.

Eliminazione di un target tramite l'interfaccia utente

Non è possibile eliminare una destinazione " IBM Cloud Activity Tracker Event Routing " se questa è utilizzata in un percorso o come impostazione predefinita per una destinazione.

1. Accedi al tuo account IBM Cloud.
2. Fai clic sull' Menu > Osservabilità.
3. Seleziona " Monitoraggio attività ".
4. Selezionare l'elemento da eliminare e fare clic .
5. Fare clic su Elimina e poi su Elimina nel pannello di conferma.

Elencare tutti gli obiettivi in una regione utilizzando l'interfaccia utente

1. Accedi al tuo account IBM Cloud.
2. Fai clic sull' Menu > Osservabilità.
3. Seleziona " Monitoraggio attività ".

La tabella riporta tutti i dettagli relativi agli obiettivi:

• Tipo di destinazione
• Nome destinazione
• Regione di destinazione
• Percorsi: se viene utilizzato in qualsiasi percorso
• Stato dell'obiettivo:
  • Attivo: il target funziona come previsto
  • Errore: la destinazione non è configurata correttamente e gli eventi non verranno indirizzati alla destinazione. Aggiorna i dettagli o la destinazione del tuo target per correggere la configurazione del target o elimina il target se non è più necessario