Destinations de l'API

Les destinations d'EventBridgeAPI Amazon sont des points de terminaison HTTP que vous pouvez appeler comme cible d'une règle, de la même manière que vous appelez unAWS service ou une ressource en tant que cible. À l'aide des destinations d'API, vous pouvez acheminer des événements entre lesAWS services, les applications SaaS (logiciel en tant que service) intégrées et vos applications vers l'extérieur à l'aideAWS d'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. AvecEventBridge, vous pouvez utiliser n'importe quelle méthode HTTP à l'exception de CONNECT et TRACE pour la demande. Les méthodes HTTP les plus courantes 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, veuillez consulter Transformation desEventBridge entrées Amazon.

Important

EventBridgeles requêtes adressées à un point de destination d'API doivent avoir un délai d'exécution client maximal de 5 secondes. Si le point de terminaison cible met plus de 5 secondes à répondre, le délai de réponseEventBridge de la demande est expiré. EventBridgeles tentatives ont dépassé le délai imparti, jusqu'au maximum configuré dans votre politique de nouvelles tentatives. Par défaut, les maximums sont de 24 heures et 185 fois. Après le nombre maximum de tentatives, les événements sont envoyés dans votre file d'attente de lettres mortes, si vous en avez une. Sinon, l'événement est abandonné.

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

Dans cette rubrique :

• Connexions pour les destinations d'API
• Crée une destination d'API
• Rôle lié à un service pour les destinations d'API
• En-têtes inclus dans les demandes destinées aux destinations d'API
• Codes d'erreur de destination de l'API
• Comment le taux d'invocation affecte la diffusion des événements
• Partenaires de destination de l'API

Connexions pour les destinations d'API

Lorsque vous créez une destination d'API, vous spécifiez une connexion destinée à son utilisation. Une connexion spécifie le type d'autorisation et les paramètres à utiliser avec le point de terminaison de destination de l'API. Vous pouvez choisir une connexion existante depuis votre compte ou créer une connexion lorsque vous créez une destination d'API. EventBridgeprend en charge les autorisations Basic, OAuth et API par clé.

Pour l'autorisation de base et l'autorisation par clé d'EventBridgeAPI, renseigne les en-têtes d'autorisation requis pour vous. Pour l'autorisation OAuth, échangezEventBridge également votre identifiant client et votre secret contre un jeton d'accès, puis gérez-le en toute sécurité. Lorsque vous créez une connexion, vous pouvez également inclure les paramètres d'en-tête, de corps et de requête requis pour l'autorisation avec un point de terminaison. Vous pouvez utiliser la même connexion pour plusieurs destinations d'API si l'autorisation pour le point de terminaison est la même.

Les jetons OAUTH sont actualisés lorsqu'une réponse 401 ou 407 est renvoyée.

Lorsque vous créez une connexion et ajoutez des paramètres d'autorisation,EventBridge crée un code secret dansAWS Secrets Manager. Le coût de stockage du secret de Secrets Manager est inclus dans les frais d'utilisation d'une destination d'API. Pour en savoir plus sur les meilleures pratiques en matière d'utilisation de secrets avec des destinations d'API, consultez AWS::Events::ApiDestinationle Guide deCloudFormation l'utilisateur.

Note

Pour créer ou mettre à jour une connexion avec succès, vous devez utiliser un compte autorisé à utiliser Secrets Manager. L'autorisation requise est incluse dans leAmazonEventBridgeFullAccess politique. La même autorisation est accordée au rôle lié au service créé dans votre compte pour la connexion.

Pour créer une connexion

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

2. Dans le panneau de navigation de gauche, choisissez destinations d'API.

3. Faites défiler la page jusqu'au tableau des destinations de l'API, puis choisissez l'onglet Connexions.

4. Choisissez Créer une connexion.

5. Sur la page Créer une connexion, entrez un nom de connexion pour la connexion.

6. Entrez une description pour la connexion.

7. Dans Type d'autorisation, sélectionnez le type d'autorisation à utiliser pour autoriser les connexions au point de terminaison HTTP spécifié pour la destination d'API qui utilise cette connexion. Effectuez l'une des actions suivantes :

   • Choisissez Basic (nom d'utilisateur/mot de passe), puis entrez le nom d'utilisateur et le mot de passe à utiliser pour autoriser avec le point de terminaison HTTP.

   • Choisissez les informations d'identification du client OAuth, puis entrez le point de terminaison d'autorisation, la méthode HTTP, l'ID client et le secret client à utiliser pour autoriser avec le point de terminaison.

     Sous Paramètres HTTP OAuth, ajoutez tous les paramètres supplémentaires à inclure pour l'autorisation avec le point de terminaison d'autorisation. Sélectionnez un paramètre dans la liste déroulante, puis entrez une clé et une valeur. Pour inclure un paramètre supplémentaire, choisissez Ajouter un paramètre.

     Sous Paramètres HTTP d'invocation, ajoutez tous les paramètres supplémentaires à inclure dans la demande d'autorisation. Pour ajouter un paramètre, sélectionnez-le dans la liste déroulante, puis entrez une clé et une valeur. Pour inclure un paramètre supplémentaire, choisissez Ajouter un paramètre.

   • Choisissez la clé d'API, puis entrez le nom de la clé d'API et la valeur associée à utiliser pour l'autorisation de la clé d'API.

     Sous Paramètres HTTP d'invocation, ajoutez tous les paramètres supplémentaires à inclure dans la demande d'autorisation. Pour ajouter un paramètre, sélectionnez-le dans la liste déroulante, puis entrez une clé et une valeur. Pour inclure un paramètre supplémentaire, choisissez Ajouter un paramètre.

8. Sélectionnez Create (Créer).

Pour modifier une connexion

1. Ouvrez la page des destinations de l'API, puis choisissez Connexions.

2. Dans le tableau Connexions, choisissez la connexion à modifier.

3. Sur la page Détails de la connexion, choisissez Modifier.

4. Mettez à jour les valeurs de la connexion, puis choisissez Mettre à jour.

Annuler l'autorisation des connexions

Lorsque vous annulez l'autorisation d'une connexion, tous les paramètres d'autorisation sont supprimés. La suppression des paramètres d'autorisation supprime le secret de la connexion. Vous pouvez donc le réutiliser sans avoir à créer une nouvelle connexion.

Note

Vous devez mettre à jour toutes les destinations d'API qui utilisent la connexion non autorisée pour utiliser une autre connexion afin d'envoyer correctement des demandes au point de terminaison de destination de l'API.

Pour annuler l'autorisation d'une connexion

1. Dans le tableau Connexions, choisissez la connexion.

2. Sur la page Détails de la connexion, choisissez Annuler l'autorisation.

3. Dans la connexion Deauthorization ? dans la boîte de dialogue, saisissez le nom de la connexion, puis choisissez Supprimer l'autorisation.

L'état de la connexion passe à Désautorisation jusqu'à ce que le processus soit terminé. Ensuite, le statut passe à Non autorisé. Vous pouvez maintenant modifier la connexion pour ajouter de nouveaux paramètres d'autorisation.

Crée une destination d'API

Chaque destination d'API nécessite une connexion. Une connexion spécifie le type d'autorisation et les informations d'identification à utiliser avec le point de terminaison de destination de l'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 créer une destination d'API

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

2. Dans le panneau de navigation de gauche, choisissez destinations d'API.

3. Faites défiler la page jusqu'au tableau des 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, chiffres, points (.), tiret (-) ou trait de soulignement (_).

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

5. Entrez une description pour la destination de l'API.

6. Saisissez un point de terminaison d'API pour la destination d'API. Le point de terminaison de destination de l'API est un point de terminaison d'appel 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 ce point de terminaison. L'URL doit utiliser HTTPS.

7. Entrez la méthode HTTP à utiliser pour vous connecter au point de terminaison de destination de l'API.

8. (Facultatif) Dans le champ Limite du taux d'appel par seconde, entrez le nombre maximum d'appels par seconde à envoyer au point de terminaison de destination de l'API.

   La limite de débit que vous définissez peut affecter la manière dont lesEventBridge événements sont organisés. Pour plus d'informations, veuillez consulter Comment le taux d'invocation affecte la diffusion des événements.

9. Pour Connection, 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. Sélectionnez Create (Créer).

Une fois que vous avez créé une destination d'API, vous pouvez la sélectionner comme cible d'une règle. Pour utiliser une destination d'API comme cible, vous devez fournir un rôle IAM avec les autorisations appropriées. Pour de plus amples informations, consultez Autorisations requises pour accéder EventBridge aux cibles à l'aide de rôles IAM.

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

Lorsque vous créez une connexion pour une destination d'API pour une destination d'API, un rôle lié au service nommé AWSServiceRoleForAmazonEventBridgeApiDestinations est ajouté à votre compte. EventBridgeutilise 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,EventBridge associe la AmazonEventBridgeApiDestinationsServiceRolepolitique de politique au rôle. La politique limite les autorisations accordées uniquement à celles 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 la 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 l'utilisation des rôles liés à un service, consultez Utilisation des rôles liés à un service dans la documentation IAM.

En-têtes inclus dans les demandes destiné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/EventBridge/ApiDestinations
Content-Type	application/json ; charset=utf-8
Range	octets=0-1048575
Codage d'acceptation	gzip, deflate
Connexion	close
Content-Length	En-tête d'entité qui indique la taille du corps de l'entité, en octets, envoyé au destinataire.
Host (Hôte)	En-tête de demande qui spécifie l'hôte et le numéro de port du serveur auquel la demande est envoyée.

Codes d'erreur de destination de l'API

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

• Les événements associés aux codes d'erreur 429 et 5xx sont relancés.

• Les événements associés aux codes d'erreur 1xx, 2xx, 3xx et 4xx (à l'exception de 429) ne sont pas relancés.

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

Comment le taux d'invocation affecte la diffusion des é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 risquent de ne pas être transmis dans les 24 heures qui suivent la nouvelle tentative d'événement. Par exemple, si vous définissez le taux d'invocation à 10 appels par seconde, mais que des milliers d'événements sont générés par seconde, vous aurez rapidement un arriéré d'événements à livrer dépassant les 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 appels ont échoué afin de pouvoir les traiter ultérieurement. Pour plus d'informations, veuillez consulter Politique relative aux nouvelles tentatives d'événements et utilisation de files d'attente de lettres mortes.