Event Streams-Ziele verwalten

Sie können „ IBM® Event Streams for IBM Cloud® “-Ziele ( Event Streams ) in Ihrem Konto mithilfe der CLI unter IBM Cloud Activity Tracker Event Routing, der REST-API unter IBM Cloud Activity Tracker Event Routing und Terraform-Skripten verwalten. Ein Ziel ist eine Ressource, in der Sie Prüfereignisse sammeln können.

Weitere Informationen zu IBM Cloud Activity Tracker Event Routing-Zielen finden Sie unter Ziele.

IAM-Zugriffsberechtigung

Sie müssen Benutzern IAM-Berechtigungen, um Ziele zu verwalten. Weitere Informationen finden Sie unter Zugriff auf Ressourcen zuweisen.

Wenn Sie eine Richtlinie definieren, können Sie den Geltungsbereich der Berechtigungen angeben. Sie können Berechtigungen für eine bestimmte Region oder für das gesamte Konto erteilen.

Wenn Sie über die IAM-Berechtigung zum Erstellen von Richtlinien und Berechtigungen verfügen, können Sie nur die Zugriffsebene gewähren, die Sie als Benutzer des Zieldienstes haben. Wenn Sie beispielsweise über Leserechte für den Zieldienst verfügen, können Sie für die Autorisierung ausschließlich die Rolle „Leser“ zuweisen. Wenn Sie versuchen, eine höhere Berechtigung, wie z. B. Administrator, zuzuweisen, sieht es so aus, als ob die Berechtigung erteilt wird, jedoch wird nur die höchste Berechtigungsstufe, die Sie für den Zieldienst haben, d. h. Viewer, zugewiesen.

Benutzer mit regionalem Zugriffsbereich können nur auf Ziele in ihrer autorisierten Region zugreifen.

IAM-Aktionen und die IAM-Rollen, die sie beinhalten.
IAM-AKTION Geltungsbereich der IAM-Richtlinie IAM-Rollen Beschreibung
atracker.target.read Bereich Administrator
Editor
Viewer
Operator
Informationen zu einem Ziel lesen (anzeigen)
atracker.target.create Bereich Administrator
Editor
Ziel erstellen
atracker.target.update Bereich Administrator
Editor
Ziel aktualisieren
atracker.target.delete Bereich Administrator
Editor
Ziel löschen
atracker.target.list Konto Administrator
Editor
Viewer
Operator
Alle Ziele auflisten

IAM-Zugriff für Event Streams

Wenn Sie den Zugriff auf ein einzelnes Event Streams-Topic beschränken müssen, müssen Sie zwei Richtlinien erstellen:

  • Eine Richtlinie für das Topic mit der Rolle "Schreibberechtigter" und die resource ID mit dem Namen des Topics
  • Eine Richtlinie für den Cluster mit der Rolle des Leseberechtigten.

Weitere Informationen finden Sie in der Dokumentation zu IBM® Event Streams for IBM Cloud®.

Authentifizierungsoptionen

Beim Schreiben an ein Event Streams-Ziel können Sie eine der folgenden Optionen verwenden, um sich bei einem IBM® Event Streams for IBM Cloud®-Thema zu authentifizieren.

  • Durch die Konfiguration der Service-to-Service-Autorisierung ( S2S ) (empfohlen).
  • Durch die Bereitstellung eines API-Schlüssels beim Konfigurieren des Ziels.

Sie können die Service-zu-Service-Autorisierung für Ihr „ Event Streams “-Thema so konfigurieren, dass Sie beim Schreiben Ihrer Daten in das „ Event Streams “-Thema keinen API-Schlüssel übergeben müssen.

CLI-Voraussetzungen

Bevor Sie die Befehlszeilenschnittstelle zum Verwalten von Zielen verwenden, führen Sie die folgenden Schritte aus:

  1. Installieren Sie die IBM Cloud-Befehlszeilenschnittstelle.

  2. Installieren Sie die IBM Cloud Activity Tracker Event Routing CLI.

    Zum Ausführen der Befehle der „ Event Streams “-CLI ist die „ atracker “-CLI 0.3.2 oder höher erforderlich. Wenn Sie zuvor die atracker-CLI installiert haben, müssen Sie möglicherweise ein Upgrade des atracker-CLI-Plug-ins durchführen, indem Sie ibmcloud plugin update atracker ausführen.

  3. Melden Sie sich bei IBM Cloud an. Führen Sie den folgenden Befehl aus: ibmcloud login

Abrufen Ihres Event Streams Instanz-API-Schlüssels

Informationen zum Erhalt Ihres Event Streams Instanz-API-Schlüssels finden Sie unter Erzeugen eines API-Schlüssels für den Zugriff auf ein Thema.

Konfiguration der „ S2S “-Autorisierung über die Benutzeroberfläche innerhalb desselben Kontos

Gehen Sie wie folgt vor, um eine Service-zu-Service-Autorisierung über die Benutzerschnittstelle von IBM Cloud zu konfigurieren.

  1. Melden Sie sich bei Ihrem IBM Cloud-Konto als Kontoeigner an, der IBM Cloud Activity Tracker Event Routing-Ziele konfigurieren möchte.

    Nach der Anmeldung mit Ihrer Benutzer-ID und Ihrem Kennwort wird das IBM Cloud-Dashboard geöffnet.

  2. Klicken Sie auf „Verwalten“ > Zugriff (IAM). „ Zugriff und Benutzer verwalten “ wird angezeigt.

  3. Klicken Sie auf Autorisierungen.

  4. Klicken Sie auf Erstellen.

  5. Wählen Sie unter „Quelldienst“ Activity Tracker und wählen Sie unter „Wie möchten Sie den Zugriff einschränken?“ die Option „Alle Ressourcen “ aus.

  6. Wählen Sie unter „Ziel-Dienst“ Message Hub Wählen Sie unter „Wie möchten Sie den Zugriff einschränken?“ die Option „Ressourcen basierend auf ausgewählten Attributen“ aus.

  7. Wählen Sie „ Service-Instanz “ und „ Zeichenkette ist gleich “ den Namen Ihrer „ Event Streams “-Instanz.

  8. Wählen Sie für den Dienstzugriff „Writer“ aus.

  9. Klicken Sie auf Autorisieren. Ihre neue Service-zu-Service-Autorisierung wird in der Ansicht Berechtigungen verwalten aufgelistet.

Konfiguration der „ S2S “-Autorisierung über die CLI

Gehen Sie wie folgt vor, um eine Service-zu-Service-Autorisierung über die Befehlszeilenschnittstelle von IBM Cloud zu konfigurieren.

  1. Melden Sie sich bei Ihrem „ IBM Cloud “-Konto an als Kontoinhaber, der die Autorisierung für „ IBM Cloud Activity Tracker Event Routing “ einrichten wird.

  2. Erstellen Sie eine Autorisierungsrichtlinie, die Ihre Service-zu-Service-Autorisierung definiert.

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

    Dabei gilt:

    IES_SERVICE_INSTANCE ist die CRN der zu autorisierenden Event Streams Instanz.

Konfiguration der „ S2S “-Autorisierung über die API

Gehen Sie wie folgt vor, um eine Service-zu-Service-Autorisierung über die API von IBM Cloud zu konfigurieren.

  1. Melden Sie sich bei Ihrem IBM Cloud-Konto als Kontoeigner an, der die IAM-Autorisierung fü IBM Cloud Activity Tracker Event Routing konfigurieren möchte.

  2. Erstellen Sie die Datei authorization_policy_resource.json, die Ihre Service-zu-Service-Autorisierung definiert.

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

    Dabei gilt:

    CUSTOMER_ACCOUNT_ID ist die Konto-GUID für das Konto, über das Ziele konfiguriert werden. Diese kann mit dem Befehl ibmcloud account list ermittelt werden.

    IES_SERVICE_INSTANCE ist die CRN der zu autorisierenden IES-Instanz.

  3. Rufen Sie ein IAM-Zugriffstoken ab. Weitere Informationen finden Sie unter Abrufen von IAM-Zugriffstokens.

  4. Führen Sie den folgenden Befehl aus, um Ihre Service-zu-Service-Autorisierung zu konfigurieren:

    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"
    

Event Streams-Ziel über die Befehlszeilenschnittstelle erstellen

Verwenden Sie diesen Befehl, um ein „ IBM® Event Streams for IBM Cloud® “-Ziel zu erstellen, mit dem ein Ziel für Aktivitätsereignisse konfiguriert werden kann.

 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]

Befehlsoptionen

--region REGION | -r REGION

Name der Region, z. B. us-south oder eu-gb. Wenn nicht angegeben, wird die Region verwendet, die protokolliert oder als Ziel verwendet wird.

--name TARGET_NAME

Der Name, der für das Ziel angegeben werden soll.

Schließen Sie keine personenbezogenen Daten in Ressourcennamen ein.

--type TARGET_TYPE

Setzen Sie TARGET_TYPE für ein Event Streams-Ziel auf event_streams.

--file @EVENTSTREAMS_ENDPOINT_DEFINITION_JSON_FILE

Eine Datei, die eine Endpunktdefinition im folgenden Format enthält:

{
  "target_crn": "yyyyy",
  "brokers": ["broker-1:9093","broker-2:9093"],
  "topic": "my-topic",
  "api_key": "xxxxxxxxxxxxxx"
}
--target-crn EVENTSTREAMS_TARGET_CRN

Die CRN der IBM® Event Streams for IBM Cloud®-Instanz. Sie können den Quellen-CRN aus den Serviceberechtigungsnachweisen abrufen.

--brokers BROKER_LIST

Die Liste der Event Streams-Broker (Endpunkte) Dies ist der Wert von kafka_brokers_sasl in den Serviceberechtigungsnachweisen.

--topic TOPIC

Event Streams Name des Themas, an das die Ereignisse gesendet werden. Dies ist der Name des Themas, das für eine Event Streams-Instanz erstellt wurde.

--api-key EVENTSTREAMS_API_KEY | @EVENTSTREAMS_API_KEY_FILE

Der im Event Streams-Serviceberechtigungsnachweis gefundene Kennwortwert. Dies ist der IAM-API-Schlüssel.

--service-to-service-enabled

Ermittelt, ob IBM Cloud Activity Tracker Event Routing die Authentifizierung von Dienst zu Dienst aktiviert hat. Setzen Sie dieses Flag auf true, wenn service to service aktiviert ist und Sie keinen apikey angeben.

--output FORMAT

Das derzeit unterstützte Format ist JSON. Falls angegeben, wird die Ausgabe im JSON-Format zurückgegeben. Wenn JSON nicht angegeben ist, wird die Ausgabe in einem Tabellenformat zurückgegeben.

help | --help | -h

Hiermit können Sie Optionen auflisten, die für den Befehl verfügbar sind.

Beispiel

Im Folgenden sehen Sie ein Beispiel für die Verwendung des Befehls ibmcloud atracker target create --name new-target-name --type event-streams --target-crn "crn:v1:bluemix:public:messagehub:eu-de:a/11111111111111111111111111111111:22222222-2222-2222-2222-222222222222::" --brokers "broker-1:9093,broker-2:9093" --topic "topic-name" --api-key xxxxx.

Dieses Beispiel zeigt ein Beispiel für eine erfolgreiche Zielerstellung.

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

Event Streams-Ziel über die Befehlszeilenschnittstelle aktualisieren

Verwenden Sie diesen Befehl, um ein „ Event Streams “-Ziel für eine „ IBM Cloud Activity Tracker Event Routing “-Region zu aktualisieren. Jeder angegebene Wert, der sich von dem Zeitpunkt, zu dem das Ziel ursprünglich erstellt wurde, unterscheidet, wird auf den im Befehl angegebenen Wert aktualisiert.

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]

Befehlsoptionen

--region REGION | -r REGION

Name der Region, z. B. us-south oder eu-gb. Wenn nicht angegeben, wird die Region verwendet, die protokolliert oder als Ziel verwendet wird.

--target TARGET

Die ID oder der aktuelle Zielname.

--name TARGET_NAME

Der Name, der für das Ziel angegeben werden soll.

Schließen Sie keine personenbezogenen Daten in Ressourcennamen ein.

--file @EVENTSTREAMS_ENDPOINT_DEFINITION_JSON_FILE

Eine Datei, die eine Endpunktdefinition im folgenden Format enthält:

{
  "endpoint": "aaaaa",
  "target_crn": "yyyyy",
  "bucket": "zzzzzz",
  "api_key": "xxxxxx"
}

oder für ein Szenario, bei dem die Service-zu-Service-Authentifizierung aktiviert ist:

{
  "target_crn": "yyyyy",
  "brokers": ["broker-1:9093","broker-2:9093"],
  "topic": "my-topic",
  "api_key": "xxxxxxxxxxxxxx"
}
--target-crn EVENTSTREAMS_TARGET_CRN

Die CRN der IBM® Event Streams for IBM Cloud®-Instanz. Sie können den Quellen-CRN aus den Serviceberechtigungsnachweisen abrufen.

--brokers BROKER_LIST

Die Liste der Event Streams-Broker (Endpunkte) Dies ist der Wert von kafka_brokers_sasl in den Serviceberechtigungsnachweisen.

--topic TOPIC

Event Streams Name des Themas, an das die Ereignisse gesendet werden. Dies ist der Name des Themas, das für eine Event Streams-Instanz erstellt wurde.

--api-key EVENTSTREAMS_API_KEY | @EVENTSTREAMS_API_KEY_FILE

Der im Event Streams-Serviceberechtigungsnachweis gefundene Kennwortwert. Dies ist der IAM-API-Schlüssel

--service-to-service-enabled

Ermittelt, ob IBM Cloud Activity Tracker Event Routing die Authentifizierung von Dienst zu Dienst aktiviert hat. Setzen Sie dieses Flag auf true, wenn service to service aktiviert ist und Sie keinen apikey angeben.

--output FORMAT

Das derzeit unterstützte Format ist JSON. Falls angegeben, wird die Ausgabe im JSON-Format zurückgegeben. Wenn JSON nicht angegeben ist, wird die Ausgabe in einem Tabellenformat zurückgegeben.

help | --help | -h

Hiermit können Sie Optionen auflisten, die für den Befehl verfügbar sind.

Beispiel

Im Folgenden sehen Sie ein Beispiel für die Verwendung des Befehls ibmcloud atracker target update --target my-target --name new-target-name.

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

Ziel über die Befehlszeilenschnittstelle löschen

Verwenden Sie diesen Befehl, um ein Ziel zu löschen.

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

Befehlsoptionen

--target TARGET
Die ID oder der Name des Ziels.
--force | -f
Das Ziel wird gelöscht, ohne dass dem Benutzer eine zusätzliche Eingabeaufforderung zur Verfügung gestellt wird.
help | --help | -h
Hiermit können Sie Optionen auflisten, die für den Befehl verfügbar sind.

Beispiel

Im Folgenden sehen Sie ein Beispiel für die Verwendung des Befehls ibmcloud atracker target rm --target xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx.

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.

Im Folgenden sehen Sie ein Beispiel für die Verwendung des Befehls ibmcloud atracker target rm --target xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx -force.

Dieses Beispiel zeigt einen fehlgeschlagenen Befehl, bei dem das angegebene Ziel nicht gefunden werden konnte.

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.

Ziel über die Befehlszeilenschnittstelle validieren

Verwenden Sie diesen Befehl, um zu prüfen, ob ein Ziel ordnungsgemäß für eine IBM Cloud Activity Tracker Event Routing-Region konfiguriert ist.

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

Befehlsoptionen

--target TARGET
Die ID oder der Name des Ziels.
--region REGION | -r REGION
Name der Region, z. B. us-south oder eu-gb. Wenn nicht angegeben, wird die Region verwendet, die protokolliert oder als Ziel verwendet wird.
--output FORMAT
Das derzeit unterstützte Format ist JSON. Falls angegeben, wird die Ausgabe im JSON-Format zurückgegeben. Wenn JSON nicht angegeben ist, wird die Ausgabe in einem Tabellenformat zurückgegeben.
help | --help | -h
Hiermit können Sie Optionen auflisten, die für den Befehl verfügbar sind.

Beispiel

Im Folgenden sehen Sie ein Beispiel für die Verwendung des Befehls ibmcloud atracker target validate --target new-target-name.

Dieses Beispiel zeigt ein erfolgreich validiertes „ Event Streams “-Ziel.

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

Informationen zu einem Ziel über die Befehlszeilenschnittstelle abrufen

Verwenden Sie diesen Befehl, um Informationen zu einem Ziel für eine IBM Cloud Activity Tracker Event Routing-Region abzurufen.

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

Befehlsoptionen

--target TARGET
Die ID oder der Name des Ziels.
--output FORMAT
Das derzeit unterstützte Format ist JSON. Falls angegeben, wird die Ausgabe im JSON-Format zurückgegeben. Wenn JSON nicht angegeben ist, wird die Ausgabe in einem Tabellenformat zurückgegeben.
help | --help | -h
Hiermit können Sie Optionen auflisten, die für den Befehl verfügbar sind.

Beispiel

Im Folgenden finden Sie ein Beispiel für die Verwendung des ibmcloud atracker target get --target new-target-name Befehls, der ein Ziel vom Typ „ Event Streams “ zeigt.

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

Alle Ziele in einer Region auflisten

Verwenden Sie diesen Befehl, um die konfigurierten Ziele für eine IBM Cloud Activity Tracker Event Routing-Region aufzulisten.

ibmcloud atracker target ls [--output FORMAT]

Befehlsoptionen

--output FORMAT
Das derzeit unterstützte Format ist JSON. Falls angegeben, wird die Ausgabe im JSON-Format zurückgegeben. Wenn JSON nicht angegeben ist, wird die Ausgabe in einem Tabellenformat zurückgegeben.
help | --help | -h
Hiermit können Sie Optionen auflisten, die für den Befehl verfügbar sind.

Beispiel

Im Folgenden sehen Sie ein Beispiel für die Verwendung des Befehls ibmcloud atracker target ls.

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

API-Ziele und -Aktionen

In der folgenden Tabelle sind die Aktionen aufgelistet, die Sie ausführen können, um Ziele zu verwalten:

Gezielte Aktionen durch Verwendung der IBM Cloud Activity Tracker Event Routing REST-API
Aktion REST-API-Methode API_URL
Ziel erstellen POST <ENDPOINT>/api/v2/targets
Ziel aktualisieren PUT <ENDPOINT>/api/v2/targets/<TARGET_ID>
Ziel löschen DELETE <ENDPOINT>/api/v2/targets/<TARGET_ID>
Ziel lesen GET <ENDPOINT>/api/v2/targets/<TARGET_ID>
Alle Ziele auflisten GET <ENDPOINT>/api/v2/targets
Ziel validieren POST <ENDPOINT>/api/v2/targets/{id}/validate

Sie können private und öffentliche Endpunkte verwenden, um Ziele zu verwalten. Weitere Informationen zu der Liste der verfügbaren ENDPOINTS finden Sie unter Endpunkte.

  • Sie können Ziele aus dem privaten Netz mithilfe eines API-Endpunkts im folgenden Format verwalten: https://private.REGION.atracker.cloud.ibm.com

  • Sie können Ziele über das öffentliche Netz mithilfe eines API-Endpunkts im folgenden Format verwalten: https://REGION.atracker.cloud.ibm.com

  • Sie können die öffentlichen Endpunkte inaktivieren, indem Sie die Kontoeinstellungen aktualisieren. Weitere Informationen finden Sie unter Ziel- und Regionseinstellungen konfigurieren.

Weitere Informationen zu der REST-API finden Sie unter Ziele.

API-Voraussetzungen

Führen Sie die folgenden Schritte aus, um API-Aufrufe zum Verwalten von Zielen zu erstellen:

  1. Rufen Sie ein IAM-Zugriffstoken ab. Weitere Informationen finden Sie unter Abrufen von IAM-Zugriffstokens.
  2. Ermitteln Sie den API-Endpunkt in der Region, in der Sie ein Ziel konfigurieren oder verwalten möchten. Weitere Informationen finden Sie unter Endpunkte.

Erstellen eines Event Streams-Ziels mithilfe der API

Mit dem folgenden curl-Befehl können Sie ein Ziel für „ IBM® Event Streams for IBM Cloud® “ ( Event Streams ) erstellen:

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

Wo

  • TARGET_NAME ist der Name des Ziels. Der Name hat eine maximal zulässige Länge von 256 Zeichen.

    Schließen Sie keine personenbezogenen Daten in Ressourcennamen ein.

  • TARGET_TYPE ist der Typ des Ziels. Legen Sie für ein Event Streams-Ziel den Wert event_streams fest.

  • BROKER_LIST ist die Liste der Event Streams-Broker (Endpunkte).

  • TOPIC_NAME ist der Name eines Event Streams-Topics, an das die Ereignisse gesendet werden.

  • API_KEY ist der Kennwortwert im Berechtigungsnachweis des Event Streams-Service. Dies ist der IAM-API-Schlüssel.

  • service_to_service_enabled bestimmt, ob IBM Cloud Activity Tracker Event Routing die Authentifizierung von Dienst zu Dienst aktiviert hat. Setzen Sie dieses Flag auf true, wenn service to service aktiviert ist und Sie keinen apikey angeben.

In der Antwort erhalten Sie Informationen zu dem Ziel, wie z. B. id, das die GUID des Ziels angibt, und crn, das die CRN des Ziels angibt.

Event Streams-Ziel über die API aktualisieren

Wenn Sie ein Ziel unter IBM® Event Streams for IBM Cloud® ( Event Streams ) aktualisieren, müssen Sie die Zielinformationen im Datenabschnitt der Anfrage angeben.

  • Sie müssen alle Felder übergeben.
  • Aktualisieren Sie die Felder, die geändert werden müssen.
  • Sobald es erstellt wurde, können Sie den Typ (target_type) eines Ziels nicht mehr ändern.

Mit dem folgenden cURL-Befehl können Sie ein Ziel aktualisieren:

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

Wo

  • TARGET_ID ist die ID des Ziels.

  • TARGET_NAME ist der Name des Ziels. Der Name hat eine maximal zulässige Länge von 256 Zeichen.

    Schließen Sie keine personenbezogenen Daten in Ressourcennamen ein.

  • TARGET_TYPE ist der Typ des Ziels. Legen Sie für ein Event Streams-Ziel den Wert event_streams fest.

  • BROKER_LIST ist die Liste der Event Streams-Broker (Endpunkte).

  • TOPIC_NAME ist der Name eines Event Streams-Topics, an das die Ereignisse gesendet werden.

  • API_KEY ist der Kennwortwert im Berechtigungsnachweis des Event Streams-Service. Dies ist der IAM-API-Schlüssel.

  • service_to_service_enabled bestimmt, ob IBM Cloud Activity Tracker Event Routing die Authentifizierung von Dienst zu Dienst aktiviert hat. Setzen Sie dieses Flag auf true, wenn service to service aktiviert ist und Sie keinen apikey angeben.

Ziel mit der API löschen

Mit dem folgenden cURL-Befehl können Sie ein Ziel löschen:

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

Wo

  • <ENDPOINT> ist der API-Endpunkt in der Region, in der Sie ein Ziel konfigurieren oder verwalten wollen. Weitere Informationen finden Sie unter Endpunkte.
  • <TARGET_ID> ist die ID des Ziels.

Sie können beispielsweise die folgende cURL-Anforderung verwenden, um ein Ziel in der Region 'USA (Süden)' mit der ID 00000000-0000-0000-0000-000000000000 zu löschen:

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"

Wenn der Löschvorgang erfolgreich war, wird als Antwort ein leeres Ergebnis zurückgegeben:

{}

Ziel mit der API validieren

Sie können den folgenden cURL-Befehl verwenden, um ein Ziel zu validieren, indem Sie die Berechtigungsnachweise zum Schreiben in das Ziel überprüfen.

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

Wo

  • <ENDPOINT> ist der API-Endpunkt in der Region, in der Sie ein Ziel konfigurieren oder verwalten wollen. Weitere Informationen finden Sie unter Endpunkte.
  • <TARGET_ID> ist die ID des Ziels.

Sie können beispielsweise die folgende cURL-Anforderung verwenden, um ein Ziel in der Region 'USA (Süden)' mit der ID 00000000-0000-0000-0000-000000000000 zu validieren:

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"

In der Antwort finden Sie Informationen im Abschnitt „ write_status “, zum Beispiel:

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

Ziel über die API anzeigen

Sie können den folgenden cURL-Befehl verwenden, um die Konfigurationsdetails von 1 Ziel anzuzeigen:

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

Wo

  • <ENDPOINT> ist der API-Endpunkt in der Region, in der Sie ein Ziel konfigurieren oder verwalten wollen. Weitere Informationen finden Sie unter Endpunkte.
  • <TARGET_ID> ist die ID des Ziels.

Sie können beispielsweise die folgende cURL-Anfrage ausführen, um Informationen über ein Ziel mit der ID 00000000-0000-0000-0000-000000000000 abzurufen:

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"

Die Ergebnisse zeigen an, ob das Ziel COS ("target_type": "cloud_object_storage") oder Event Streams ("target_type": "event_streams") ist.

Alle Ziele über die API auflisten

Sie können den folgenden cURL-Befehl verwenden, um alle Ziele anzuzeigen:

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

Wo

  • <ENDPOINT> ist der API-Endpunkt in der Region, in der Sie ein Ziel konfigurieren oder verwalten wollen. Weitere Informationen finden Sie unter Endpunkte.

Sie können beispielsweise die folgende cURL-Anforderung ausführen, um Informationen zu den in der Region 'Dallas' definierten Zielen abzurufen:

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

Die Ergebnisse zeigen an, ob das Ziel COS ("target_type": "cloud_object_storage") oder Event Streams ("target_type": "event_streams") ist.

HTTP-Antwortcodes

Wenn Sie die IBM Cloud Activity Tracker Event Routing REST-API verwenden, können Sie Standard-HTTP-Antwortcodes abrufen, um anzugeben, ob eine Methode erfolgreich abgeschlossen wurde.

  • Eine Antwort von 200 zeigt immer Erfolg an.
  • Eine 4xx-Antwort weist auf einen Fehler hin.
  • Eine 5xx-Antwort weist normalerweise auf einen internen Systemfehler hin.

In der folgenden Tabelle finden Sie einige HTTP-Antwortcodes:

Liste der Antwortcodes HTTP
Statuscode Status Beschreibung
200 OK Die Anforderung war erfolgreich.
201 OK Die Anforderung war erfolgreich. Eine Ressource wird erstellt.
400 Ungültige Anforderung Die Anforderung war nicht erfolgreich. Möglicherweise fehlt ein Parameter, der erforderlich ist.
401 Nicht berechtigt Das IAM-Token, das in der API-Anforderung verwendet wird, ist ungültig oder abgelaufen.
403 Nicht zulässig Die Operation ist aufgrund unzureichender Berechtigungen nicht zulässig.
404 Nicht gefunden Die angeforderte Ressource ist nicht vorhanden oder wurde bereits gelöscht.
429 Zu viele Anforderungen Zu viele Anforderungen haben die API zu schnell getroffen.
500 Interner Serverfehler In der IBM Cloud Activity Tracker Event Routing Verarbeitung ist etwas schief gelaufen.

Event Streams-Ziel über die Benutzerschnittstelle erstellen

Nur Ressourcen in Ihrem Konto werden aufgelistet und können ausgewählt werden. Um eine Ressource in einem anderen Account anzugeben, wählen Sie CRN angeben unter Ziel auswählen aus.

  1. Melden Sie sich bei Ihrem IBM Cloud-Konto an.
  2. Klicken Sie auf das Menüsymbol Menüsymbol > Beobachtbarkeit.
  3. „Aktivitätsaufzeichnung“ auswählen...
  4. Klicken Sie auf Erstellen, um die Erstellungsanzeige zu öffnen.
  5. Typ auswählen: Klicken Sie Event Streams an.
  6. Ziel auswählen: Wählen Sie Nach Instanz suchen oder CRN angeben aus.
    • Nach Instanz suchen: Wählen Sie in der Tabelle eine Event Streams-Instanz aus oder klicken Sie auf Erstellen, um die neue Event Streams-Instanz zu erstellen.
    • CRN angeben: Geben Sie den Cloudressourcennamen (CRN) der Event Streams-Instanz ein. Dadurch können Sie einen CRN aus einem anderen Konto eingeben.
  • Serviceberechtigungsnachweise: Wählen Sie einen der Serviceberechtigungsnachweise aus. Er enthält den Benutzernamen und den API-Schlüssel oder das Kennwort für die Brokerliste.
  • AbschnittEvent Streams: Wählen Sie ein vorhandenes Thema aus.
  • Zielname: Geben Sie einen aussagekräftigen Namen für das Ziel ein.
  • Zielregion: Wählen Sie die Region aus, die die Ereignisdaten verarbeiten soll.
  • Aktivieren Sie die Option Als Standardziel festlegen, um Ihr neues Ziel automatisch als Standardziel in Ihren IBM Cloud Activity Tracker Event Routing-Einstellungen festzulegen. Weitere Informationen finden Sie in der Dokumentation zu Standardzielen.
  • Klicken Sie auf Ziel erstellen.

Event Streams-Ziel über die Benutzerschnittstelle aktualisieren

Nur Ressourcen in Ihrem Konto werden aufgelistet und können ausgewählt werden. Um eine Ressource in einem anderen Account anzugeben, wählen Sie CRN angeben unter Ziel auswählen aus.

  1. Melden Sie sich bei Ihrem IBM Cloud-Konto an.
  2. Klicken Sie auf das Menüsymbol Menüsymbol > Beobachtbarkeit.
  3. Wählen Sie „ Aktivitätsaufzeichnung “ aus.
  4. Wählen Sie das zu aktualisierende Ziel aus und klicken Sie auf das Symbol „Aktionen“ unter „ “.
  5. Sie können auf Als Standard aufheben klicken, um Ihr Ziel als Standardziel in Ihren IBM Cloud Activity Tracker Event Routing-Einstellungen zu entfernen. Weitere Informationen finden Sie in der Dokumentation zu Standardzielen.
  6. Klicken Sie auf Bearbeiten, um die Aktualisierungsanzeige zu öffnen.
  7. Details: Auf Bearbeiten klicken, um den Namen oder die Region Ihres Ziels zu aktualisieren. Sie können auch die Option Standardziel umschalten, um Ihr Ziel als Standardziel in Ihren IBM Cloud Activity Tracker Event Routing-Einstellungen hinzuzufügen oder zu entfernen.
  8. Klicken Sie auf Speichern, um Ihr Ziel zu aktualisieren.
  9. Ziel: Klicken Sie auf Bearbeiten, um die Event Streams-Instanz, den Serviceberechtigungsnachweis oder das Thema zu ändern, die bzw. das Ihrem Ziel zugeordnet ist.
  10. Klicken Sie auf Speichern, um Ihr Ziel zu aktualisieren.

Ein Ziel über die Benutzeroberfläche löschen

Ein „ IBM Cloud Activity Tracker Event Routing “-Ziel kann nicht gelöscht werden, wenn es in einer Route oder als Standardziel verwendet wird.

  1. Melden Sie sich bei Ihrem IBM Cloud-Konto an.
  2. Klicken Sie auf das Menüsymbol Menüsymbol > Beobachtbarkeit.
  3. Wählen Sie „ Aktivitätsaufzeichnung “ aus.
  4. Wählen Sie das zu löschende Ziel aus und klicken Sie auf das Symbol „Aktionen“ unter „ “.
  5. Klicken Sie auf Löschen und anschließend in der Bestätigungsanzeige auf Löschen.

Alle Ziele in einer Region über die Benutzeroberfläche auflisten

  1. Melden Sie sich bei Ihrem IBM Cloud-Konto an.
  2. Klicken Sie auf das Menüsymbol Menüsymbol > Beobachtbarkeit.
  3. Wählen Sie „ Aktivitätsaufzeichnung “ aus.

In der Tabelle sind alle Zielangaben aufgeführt:

  • Zieltyp
  • Zielname
  • Zielregion
  • Routen: Bei Verwendung in Routen
  • Zielstatus:
    • Aktiv: Das Ziel funktioniert wie erwartet.
    • Fehler: Das Ziel ist fehlerhaft konfiguriert und Ereignisse werden nicht an das Ziel weitergeleitet. Aktualisieren Sie die Zieldetails oder das Ziel, um die Zielkonfiguration zu korrigieren, oder löschen Sie das Ziel, wenn es nicht mehr benötigt wird