Destinations d’API

Les destinations EventBridge d'API Amazon sont des points de terminaison HTTP que vous pouvez invoquer en tant que cible d'une règle, de la même manière que vous invoquez un AWS service ou une ressource en tant que cible. À l'aide des destinations d'API, vous pouvez acheminer les événements entre les AWS services, les applications intégrées de type logiciel en tant que service (SaaS) et vos applications en dehors de l'extérieur en AWS utilisant des appels d'API. Lorsque vous spécifiez une destination d'API comme cible d'une règle, EventBridge invoque le point de terminaison HTTP pour tout événement correspondant au modèle d'événement spécifié dans la règle, puis fournit les informations relatives à l'événement avec la demande. Avec EventBridge, vous pouvez utiliser n'importe quelle méthode HTTP sauf CONNECT et TRACE pour la requête. Les méthodes HTTP les plus couramment utilisées sont PUT et POST. Vous pouvez également utiliser des transformateurs d’entrée pour personnaliser l’événement en fonction des paramètres d’un point de terminaison HTTP spécifique. Pour plus d’informations, consultez Transformation des EventBridge entrées Amazon.

Les destinations d’API ne prennent pas en charge les destinations privées, telles que les points de terminaison de VPC d’interface. Pour plus d’informations, consultez Utilisation d'Amazon EventBridge avec des points de terminaison de VPC d'interface .

Important

EventBridge les demandes adressées à un point de terminaison de destination de l'API doivent avoir un délai d'exécution maximal du client de 5 secondes. Si le point de terminaison cible met plus de 5 secondes à répondre, EventBridge la demande expire. EventBridge les demandes ont dépassé le délai maximum défini dans votre politique de nouvelles tentatives. Par défaut, ces valeurs maximales sont de 24 heures et 185 fois. Une fois le nombre maximal de nouvelles tentatives atteint, les événements sont envoyés à votre file d’attente de lettres mortes si vous en avez une. Sinon, l’événement est supprimé.

La vidéo suivante montre l’utilisation de la destination d’API :

Dans cette rubrique :

• Création d’une destination d’API
• Création de règles qui envoient des événements vers une destination d’API
• Rôle lié à un service pour les destinations d’API
• En-têtes dans les demandes adressées aux destinations d’API
• Codes d’erreur de destination d’API
• Comment le taux d’invocation affecte la livraison d’événements
• Envoi d' CloudEvents événements vers des destinations d'API
• Partenaires de destination d’API

Création d’une destination d’API

Chaque destination d’API requiert une connexion. Une connexion spécifie le type d’autorisation et les informations d’identification à utiliser pour être autorisée auprès du point de terminaison de destination d’API. Vous pouvez choisir une connexion existante ou créer une connexion en même temps que vous créez la destination d’API. Pour plus d’informations, consultez Connexions pour les cibles de point de terminaison HTTP.

Pour créer une destination d'API à l'aide de la EventBridge console

1. Connectez-vous à AWS l'aide d'un compte autorisé à gérer EventBridge et à ouvrir la EventBridgeconsole.

2. Dans le volet de navigation de gauche, choisissez Destinations d’API.

3. Faites défiler la page jusqu’au tableau Destinations d’API, puis choisissez Créer une destination d’API.

4. Sur la page Créer une destination d’API, entrez un Nom pour la destination d’API. Vous pouvez utiliser jusqu’à 64 lettres majuscules ou minuscules, des chiffres, des points (.), des tirets (-) ou des traits de soulignement (_).

   Le nom doit être unique pour votre compte dans la région actuelle.

5. Entrez une Description pour la destination d’API.

6. Entrez un Point de terminaison de la destination d’API pour la destination d’API. Le point de terminaison de la destination d’API est une cible de point de terminaison d’invocation HTTP pour les événements. Les informations d’autorisation que vous incluez dans la connexion utilisée pour cette destination d’API sont utilisées pour autoriser la connexion auprès de ce point de terminaison. L’URL doit utiliser HTTPS.

7. Entrez la Méthode HTTP à utiliser pour se connecter au Point de terminaison de la destination d’API.

8. (Facultatif) Dans le champ Limite du taux d’appel par seconde, entrez le nombre maximal d’invocations par seconde à envoyer au point de terminaison de destination d’API.

   La limite de débit que vous définissez peut affecter le mode de EventBridge diffusion des événements. Pour plus d’informations, consultez Comment le taux d’invocation affecte la livraison d’événements.

9. Pour Connexion, effectuez l’une des actions suivantes :

   • Choisissez Utiliser une connexion existante, puis sélectionnez la connexion à utiliser pour cette destination d’API.

   • Choisissez Créer une nouvelle connexion, puis entrez les détails de la connexion à créer. Pour plus d’informations, consultez Connexions.

10. Choisissez Créer.

Création de règles qui envoient des événements vers une destination d’API

Après avoir créé une destination d’API, vous pouvez la sélectionner en tant que cible d’une règle. Pour utiliser une destination d’API en tant que cible, vous devez fournir un rôle IAM avec les autorisations appropriées. Pour plus d’informations, consultez Autorisations nécessaires à EventBridge pour accéder à des cibles à l'aide de rôles IAM.

La sélection d’une destination d’API en tant que cible fait partie de la création de la règle.

Pour créer une règle qui envoie des événements à une destination d’API à l’aide de la console

1. Suivez les étapes de la procédure Création de règles Amazon EventBridge qui réagissent aux événements.

2. Au cours de l'Sélection des ciblesétape, lorsque vous êtes invité à choisir une destination d'API comme type de cible :

   1. Sélectionnez la destination de EventBridge l'API.

   2. Effectuez l’une des actions suivantes :

      • Choisissez Utiliser une destination d'API existante et sélectionnez une destination d'API existante

      • Choisissez Créer une nouvelle destination d'API et spécifiez le paramètre nécessaire pour définir votre nouvelle destination d'API.

        Pour plus d'informations sur la définition des paramètres requis, consultezCréation d’une destination d’API.

   3. (Facultatif) : Pour spécifier les paramètres d'en-tête de l'événement, sous Paramètres d'en-tête, choisissez Ajouter un paramètre d'en-tête.

      Spécifiez ensuite la clé et la valeur du paramètre d'en-tête.

   4. (Facultatif) : Pour spécifier les paramètres de chaîne de requête pour l'événement, sous Paramètres de chaîne de requête, choisissez Ajouter un paramètre de chaîne de requête.

      Spécifiez ensuite la clé et la valeur du paramètre de chaîne de requête.

3. Terminez la création de la règle en suivant les étapes de la procédure.

Rôle lié à un service pour les destinations d’API

Lorsque vous créez une connexion pour une destination d'API, un rôle lié à un service nommé AWS ServiceRoleForAmazonEventBridgeApiDestinationsest ajouté à votre compte. EventBridge utilise le rôle lié au service pour créer et stocker un secret dans Secrets Manager. Pour accorder les autorisations nécessaires au rôle lié au service, associez EventBridge la AmazonEventBridgeApiDestinationsServiceRolePolicypolitique au rôle. La politique limite les autorisations accordées aux autorisations nécessaires pour que le rôle interagisse avec le secret de la connexion. Aucune autre autorisation n’est incluse et le rôle ne peut interagir qu’avec les connexions de votre compte pour gérer le secret.

La politique suivante est 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/*"
        }
    ]
}

Pour plus d’informations sur les rôles lié à un service, consultez Utilisation des rôles liés à un service dans la documentation d’IAM.

Le rôle AmazonEventBridgeApiDestinationsServiceRolePolicy lié à un service est pris en charge dans les régions suivantes : AWS

• USA Est (Virginie du Nord)

• USA Est (Ohio)

• USA Ouest (Californie du Nord)

• USA Ouest (Oregon)

• Afrique (Le Cap)

• Asie-Pacifique (Hong Kong)

• Asia Pacific (Mumbai)

• Asie-Pacifique (Osaka)

• Asia Pacific (Seoul)

• Asie-Pacifique (Singapour)

• Asie-Pacifique (Sydney)

• Asie-Pacifique (Tokyo)

• Canada (Centre)

• Europe (Francfort)

• Europe (Irlande)

• Europe (Londres)

• Europe (Milan)

• Europe (Paris)

• Europe (Stockholm)

• Europe (Milan)

• Amérique du Sud (São Paulo)

• Chine (Ningxia)

• Chine (Beijing)

En-têtes dans les demandes adressées aux destinations d’API

La section suivante explique comment EventBridge gérer les en-têtes HTTP dans les demandes adressées aux destinations d'API.

En-têtes inclus dans les demandes adressées aux destinations d’API

Outre les en-têtes d'autorisation définis pour la connexion utilisée pour une destination d'API, EventBridge inclut les en-têtes suivants dans chaque demande.

Clé d’en-tête	Valeur d'en-tête
Agent utilisateur	Amazon//EventBridgeApiDestinations
Content-Type	Si aucune valeur de type de contenu personnalisée n'est spécifiée, EventBridge inclut la valeur par défaut suivante en tant que type de contenu : application/json; charset=utf-8
Range	bytes=0-1048575
Accept-Encoding	gzip,deflate
Connexion	close
Content-Length	En-tête d’entité qui indique la taille de entity-body, en octets, envoyé au destinataire.
Host (Hôte)	En-tête de demande qui indique l’hôte et le numéro de port du serveur sur lequel la demande est envoyée.

En-têtes qui ne peuvent pas être remplacés dans les demandes adressées aux destinations d’API

EventBridge ne vous permet pas de remplacer les en-têtes suivants :

• Agent utilisateur

• Range

En-têtes supprimés EventBridge des demandes destinées aux destinations de l'API

EventBridge supprime les en-têtes suivants pour toutes les demandes de destination d'API :

• A-IM

• Accept-Charset

• Accept-Datetime

• Accept-Encoding

• Cache-Control

• Connexion

• Encodage-Contenu

• Content-Length

• Content-MD5

• Date

• Expect

• Forwarded

• De

• Host (Hôte)

• HTTP2-Settings

• If-Match

• If-Modified-Since

• If-None-Match

• If-Range

• If-Unmodified-Since

• Max-Forwards

• Origin

• Pragma

• Proxy-Authorization

• Range

• Référent

• TE

• Trailer

• Transfer-Encoding

• Agent utilisateur

• Upgrade

• Via

• Avertissement

Codes d’erreur de destination d’API

Lorsque EventBridge vous essayez de transmettre un événement à une destination d'API et qu'une erreur se produit EventBridge, procédez comme suit :

• Il tente à nouveau de livrer les événements associés aux codes d’erreur 409, 429 et 5xx.

• Il ne tente pas à nouveau de livrer les événements associés aux codes d’erreur 1xx, 2xx, 3xx et 4xx (sauf 429).

EventBridge Les destinations d'API lisent l'en-tête de réponse HTTP standard Retry-After pour savoir combien de temps il faut attendre avant de faire une demande de suivi. EventBridge choisit la valeur la plus prudente entre la politique de réessai définie et l'Retry-Afteren-tête. Si Retry-After la valeur est négative, EventBridge arrête toute nouvelle tentative de livraison pour cet événement.

Comment le taux d’invocation affecte la livraison d’événements

Si vous définissez le taux d’invocation par seconde sur une valeur bien inférieure au nombre d’invocations générées, les événements peuvent ne pas être livrés dans le délai de 24 heures imparti pour les nouvelles tentatives. Par exemple, si vous définissez le taux d’invocation sur 10 invocations par seconde, mais que des milliers d’événements sont générés par seconde, votre retard au niveau des événements à livrer dépassera rapidement 24 heures. Pour vous assurer qu’aucun événement n’est perdu, configurez une file d’attente de lettres mortes à laquelle envoyer les événements dont les invocations ont échoué afin de pouvoir les traiter ultérieurement. Pour plus d’informations, consultez Politique relative aux nouvelles tentatives d'événements et utilisation de files d'attente de lettres mortes.