API-Ziele

EventBridge Amazon-API-Ziele sind HTTP-Endpunkte, die Sie als Ziel einer Regel aufrufen können, ähnlich wie Sie einen AWS Service oder eine Ressource als Ziel aufrufen. Mithilfe von API-Zielen können Sie Ereignisse mithilfe von API-Aufrufen zwischen AWS Diensten, integrierten Software-as-a-Service (SaaS) -Anwendungen und Ihren Anwendungen außerhalb AWS von weiterleiten. Wenn Sie ein API-Ziel als Ziel einer Regel angeben, EventBridge ruft es den HTTP-Endpunkt für jedes Ereignis auf, das dem in der Regel angegebenen Ereignismuster entspricht, und übermittelt dann die Ereignisinformationen zusammen mit der Anfrage. Mit EventBridge können Sie jede HTTP-Methode außer CONNECT und TRACE für die Anfrage verwenden. Die am häufigsten verwendeten HTTP-Methoden sind PUT und POST. Sie können auch Eingabe-Transformatoren verwenden, um das Ereignis an die Parameter bestimmter HTTP-Endpunktparameter anzupassen. Weitere Informationen finden Sie unter Transformation Amazon EventBridge Amazon-Eingaben.

Anmerkung

API-Ziele unterstützen keine privaten Ziele, wie z. B. Schnittstellen-VPC-Endpunkte, einschließlich privater HTTPS-APIs in Virtual Private Clouds (VPC), die private Netzwerk- und Application Load Balancer- und Schnittstellen-VPC-Endpunkte verwenden.

Weitere Informationen finden Sie unter Amazon EventBridge mit Interface VPC-Endpunkten verwenden .

Wichtig

EventBridge Anfragen an einen API-Zielendpunkt müssen ein maximales Timeout für die Client-Ausführung von 5 Sekunden haben. Wenn die Antwort des Zielendpunkts länger als 5 Sekunden dauert, kommt es bei der Anfrage zu einem EventBridge Timeout. EventBridge wiederholt Anfragen mit Timeout bis zu den Höchstwerten, die in Ihrer Wiederholungsrichtlinie konfiguriert sind. Standardmäßig sind die Höchstwerte 24 Stunden und 185 Mal. Sobald die maximale Anzahl an Wiederholungen erreicht ist, werden Ereignisse an Ihre Warteschlange für unzustellbare Nachrichten gesendet. Andernfalls wird das Ereignis gelöscht.

Das folgende Video zeigt die Verwendung des API-Ziels:

In diesem Thema:

• Erstellen eines API-Ziels
• Erstellen von Regeln, die Ereignisse an ein API-Ziel senden
• Serviceverknüpfte Rolle für API-Ziele
• Header in Anforderungen an API-Ziele
• Fehlercodes für das API-Ziel
• Wie wirkt sich die Aufrufrate auf die Ereigniszustellung aus
• CloudEvents Ereignisse werden an API-Ziele gesendet
• API-Zielpartner

Erstellen eines API-Ziels

Jedes API-Ziel erfordert eine Verbindung. Eine Verbindung gibt den Autorisierungstyp und die Anmeldeinformationen an, die zur Autorisierung mit dem API-Zielendpunkt verwendet werden. Sie können eine vorhandene Verbindung auswählen oder gleichzeitig mit der Erstellung des API-Ziels eine Verbindung erstellen. Weitere Informationen finden Sie unter Verbindungen für HTTP-Endpunktziele.

Um ein API-Ziel mit der Konsole zu erstellen EventBridge

1. Melden Sie sich AWS mit einem Konto an, das über Berechtigungen zum Verwalten EventBridge und Öffnen der EventBridgeKonsole verfügt.

2. Wählen Sie im linken Navigationsbereich API-Ziele aus.

3. Scrollen Sie nach unten zur Tabelle API-Ziele und wählen Sie dann API-Ziel erstellen aus.

4. Geben Sie auf der Seite API-Ziel erstellen einen Namen für das API-Ziel ein. Sie können bis zu 64 Groß- oder Kleinbuchstaben, Zahlen, Punkte (.), Bindestriche (-) oder Unterstriche (_) verwenden.

   Der Name muss für das Konto in der aktuellen Region eindeutig sein.

5. Geben Sie eine Beschreibung für das API-Ziel ein.

6. Geben Sie einen API-Zielendpunkt für das API-Ziel ein. Der API-Zielendpunkt ist ein HTTP-Aufrufendpunktziel für Ereignisse. Die Autorisierungsinformationen, die Sie in der für dieses API-Ziel verwendeten Verbindung angeben, werden zur Autorisierung im Hinblick auf diesen Endpunkt verwendet. Die URL muss HTTPS verwenden.

7. Geben Sie die HTTP-Methode ein, die für die Verbindung zum API-Zielendpunkt verwendet werden soll.

8. (Optional) Geben Sie für das Feld Begrenzung der Aufrufrate pro Sekunde die maximale Anzahl von Aufrufen pro Sekunde ein, die an den API-Zielendpunkt gesendet werden.

   Das von Ihnen festgelegte Ratenlimit kann sich darauf auswirken, wie EventBridge Ereignisse übertragen werden. Weitere Informationen finden Sie unter Wie wirkt sich die Aufrufrate auf die Ereigniszustellung aus.

9. Gehen Sie für Verbindung gemäß einer der folgenden Vorgehensweisen vor:

   • Wählen Sie Vorhandene Verbindung verwenden und dann die Verbindung aus, die für dieses API-Ziel verwendet werden soll.

   • Wählen Sie Neue Verbindung erstellen aus und geben Sie dann die Details für die zu erstellende Verbindung ein. Weitere Informationen finden Sie unter Verbindungen.

10. Wählen Sie Erstellen.

Erstellen von Regeln, die Ereignisse an ein API-Ziel senden

Nachdem Sie ein API-Ziel erstellt haben, können Sie es als Ziel einer Regel auswählen. Wenn Sie ein API-Ziel als Ziel verwenden möchten, müssen Sie eine IAM-Rolle mit den richtigen Berechtigungen bereitstellen. Weitere Informationen finden Sie unter Berechtigungen, die für den Zugriff EventBridge auf Ziele mithilfe von IAM-Rollen erforderlich sind.

Die Auswahl eines API-Ziels als Ziel ist Teil der Erstellung der Regel.

So erstellen Sie mithilfe der Konsole eine Regel, die Ereignisse an ein API-Ziel sendet

1. Befolgen Sie die Schritte im Verfahren Erstellen von Amazon-EventBridge-Regeln, die auf Ereignisse reagieren.

2. Wenn Sie in dem Auswählen von Zielen Schritt aufgefordert werden, ein API-Ziel als Zieltyp auszuwählen, gehen Sie wie folgt vor:

   1. Wählen Sie das EventBridge API-Ziel aus.

   2. Führen Sie eine der folgenden Aktionen aus:

      • Wählen Sie Bestehendes API-Ziel verwenden und wählen Sie ein vorhandenes API-Ziel aus

      • Wählen Sie Neues API-Ziel erstellen und geben Sie die erforderlichen Einstellungen an, um Ihr neues API-Ziel zu definieren.

        Weitere Informationen zur Angabe der erforderlichen Einstellungen finden Sie unterErstellen eines API-Ziels.

   3. (Optional): Um Header-Parameter für das Ereignis anzugeben, wählen Sie unter Header-Parameter die Option Header-Parameter hinzufügen aus.

      Geben Sie als Nächstes den Schlüssel und den Wert für den Header-Parameter an.

   4. (Optional): Um Abfragezeichenfolgenparameter für das Ereignis anzugeben, wählen Sie unter Parameter für Abfragezeichenfolge die Option Abfragezeichenfolge-Parameter hinzufügen aus.

      Geben Sie als Nächstes den Schlüssel und den Wert für den Abfragezeichenfolgenparameter an.

3. Schließen Sie die Erstellung der Regel gemäß den Verfahrensschritten ab.

Serviceverknüpfte Rolle für API-Ziele

Wenn Sie eine Verbindung für ein API-Ziel erstellen, AWS ServiceRoleForAmazonEventBridgeApiDestinationswird Ihrem Konto eine dienstbezogene Rolle mit dem Namen hinzugefügt. EventBridge verwendet die dienstverknüpfte Rolle, um ein Geheimnis in Secrets Manager zu erstellen und zu speichern. Um der dienstbezogenen Rolle die erforderlichen Berechtigungen zu gewähren, hängt die EventBridge AmazonEventBridgeApiDestinationsServiceRolePolicyRichtlinie an die Rolle an. Die Richtlinie beschränkt die gewährten Berechtigungen auf diejenigen, die für die Interaktion der Rolle mit dem Secret für die Verbindung erforderlich sind. Es sind keine weiteren Berechtigungen enthalten und die Rolle kann nur mit den Verbindungen in Ihrem Konto interagieren, um das Secret zu verwalten.

Die folgende Richtlinie ist die AmazonEventBridgeApiDestinationsServiceRolePolicy.

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Effect": "Allow",
            "Action": [
                "secretsmanager:CreateSecret",
                "secretsmanager:UpdateSecret",
                "secretsmanager:DescribeSecret",
                "secretsmanager:DeleteSecret",
                "secretsmanager:GetSecretValue",
                "secretsmanager:PutSecretValue"
            ],
            "Resource": "arn:aws:secretsmanager:*:*:secret:events!connection/*"
        }
    ]
}

Weitere Informationen zu serviceverknüpften Rollen finden Sie unter Verwenden serviceverknüpfter Rollen in der IAM-Dokumentation.

Die AmazonEventBridgeApiDestinationsServiceRolePolicy dienstbezogene Rolle wird in den folgenden Regionen unterstützt: AWS

• USA Ost (Nord-Virginia)

• USA Ost (Ohio)

• USA West (Nordkalifornien)

• USA West (Oregon)

• Africa (Cape Town)

• Asia Pacific (Hong Kong)

• Asia Pacific (Mumbai)

• Asia Pacific (Osaka)

• Asia Pacific (Seoul)

• Asien-Pazifik (Singapur)

• Asien-Pazifik (Sydney)

• Asien-Pazifik (Tokio)

• Canada (Central)

• Europe (Frankfurt)

• Europa (Irland)

• Europa (London)

• Europa (Milan)

• Europe (Paris)

• Europa (Stockholm)

• Südamerika (São Paulo)

• China (Ningxia)

• China (Peking)

Header in Anforderungen an API-Ziele

Im folgenden Abschnitt wird beschrieben, wie HTTP-Header in Anfragen an API-Ziele EventBridge behandelt werden.

Header, die in Anforderungen an API-Ziele enthalten sind

EventBridge Enthält zusätzlich zu den Autorisierungsheadern, die für die Verbindung definiert sind, die für ein API-Ziel verwendet wird, die folgenden Header in jeder Anfrage.

Header-Schlüssel	Header-Wert
Benutzer-Agent	Amazonas//EventBridgeApiDestinations
Content-Type	Wenn kein benutzerdefinierter Content-Type-Wert angegeben ist, EventBridge wird der folgende Standardwert als Content-Type verwendet: application/json; charset=utf-8
Bereich	bytes=0-1048575
Accept-Encoding	gzip,deflate
Verbindung	close
Content-Length	Ein Entity-Header, der die Größe des entity-body in Byte angibt, der an den Empfänger gesendet wird
Host	Ein Anforderungsheader, der den Host und die Portnummer des Servers angibt, an den die Anfrage gesendet wird

Header, die in Anforderungen an API-Ziele nicht überschrieben werden können

EventBridge erlaubt es Ihnen nicht, die folgenden Header zu überschreiben:

• Benutzer-Agent

• Bereich

Headers EventBridge werden aus Anfragen an API-Ziele entfernt

EventBridge entfernt die folgenden Header für alle API-Zielanfragen:

• A-IM

• Accept-Charset

• Accept-Datetime

• Accept-Encoding

• Cache-Control

• Verbindung

• Content-Encoding

• Content-Length

• Inhalt-MD5

• Datum

• Expect

• Forwarded

• Aus

• Host

• HTTP2-Settings

• If-Match

• If-Modified-Since

• If-None-Match

• If-Range

• If-Unmodified-Since

• Max-Forwards

• Urspung

• Pragma

• Proxy-Authorization

• Bereich

• Referer

• TE

• Trailer

• Transfer-Encoding

• Benutzer-Agent

• Upgrade

• Via

• Warnung

Fehlercodes für das API-Ziel

Wenn EventBridge versucht wird, ein Ereignis an ein API-Ziel zu senden, und ein Fehler auftritt, EventBridge geht Folgendes vor:

• Ereignisse, die den Fehlercodes 409, 429 und 5xx zugeordnet sind, werden wiederholt.

• Ereignisse, die den Fehlercodes 1xx, 2xx, 3xx und 4xx (außer 429) zugeordnet sind, werden nicht wiederholt.

EventBridge API-Ziele lesen den Standard-HTTP-Antwort-HeaderRetry-After, um herauszufinden, wie lange gewartet werden muss, bevor eine Folgeanfrage gestellt wird. EventBridge wählt den konservativeren Wert zwischen der definierten Wiederholungsrichtlinie und dem Retry-After Header. Wenn der Retry-After Wert negativ ist, wird der erneute Zustellungsversuch für dieses Ereignis EventBridge beendet.

Wie wirkt sich die Aufrufrate auf die Ereigniszustellung aus

Wenn Sie die Aufrufrate pro Sekunde auf einen Wert festlegen, der deutlich unter der Anzahl der generierten Aufrufe liegt, werden Ereignisse möglicherweise nicht innerhalb der 24-stündigen Wiederholungszeit für Ereignisse zugestellt. Wenn Sie beispielsweise die Aufrufrate auf 10 Aufrufe pro Sekunde festlegen, aber Tausende von Ereignissen pro Sekunde generiert werden, entsteht schnell ein Backlog an zuzustellenden Ereignissen, der 24 Stunden überschreitet. Wenn Sie sicherstellen möchten, dass keine Ereignisse verloren gehen, richten Sie eine Warteschlange für unzustellbare Nachrichten ein, an die Ereignisse mit fehlgeschlagenen Aufrufen gesendet werden, sodass Sie die Ereignisse zu einem späteren Zeitpunkt verarbeiten können. Weitere Informationen finden Sie unter Verwenden von Warteschlangen mit unzustellbaren Buchstaben zur Verarbeitung nicht zugestellter Ereignisse.