Les traductions sont fournies par des outils de traduction automatique. En cas de conflit entre le contenu d'une traduction et celui de la version originale en anglais, la version anglaise prévaudra.
# Intégration des spécifications OpenAPI
Grâce à l'intégration des spécifications OpenAPI, vous pouvez créer des intégrations personnalisées basées sur des schémas OpenAPI. Cela vous permet de vous connecter à n'importe quelle API fournissant une spécification OpenAPI. Cette intégration prend uniquement en charge l'exécution d'actions et nécessite le niveau Amazon Quick Pro ou supérieur.
## Actions possibles
L'intégration des spécifications OpenAPI fournit une connectivité basée sur des schémas pour vous aider à travailler de manière personnalisée. APIs
**Connecteur Action**
Effectuez des actions en fonction des spécifications OpenAPI. Exécutez des appels d'API, gérez les ressources et interagissez avec des services personnalisés par le biais d'actions générées dynamiquement sur la base du schéma fourni.
**Configuration basée sur un schéma**
Importez les spécifications OpenAPI pour générer automatiquement les actions et actions disponibles. Support pour la validation du schéma JSON et le mappage des paramètres.
## Avant de commencer
Avant de configurer l'intégration des spécifications OpenAPI, assurez-vous de disposer des éléments suivants :
+ Spécification OpenAPI (version 3.0.0 ou supérieure) pour votre API cible.
+ Informations d'authentification API (clé API ou autre). OAuth
+ Amazon Quick Author ou version ultérieure.
+ Documentation de l'API et accès aux terminaux.
## Préparation de la spécification et de l'authentification OpenAPI
Avant de configurer l'intégration dans Amazon Quick, préparez votre spécification OpenAPI et vos informations d'authentification. Votre spécification OpenAPI doit répondre à des exigences spécifiques pour une intégration réussie.
### Exigences de base
Votre spécification OpenAPI doit répondre à ces exigences de base.
+ Version **OpenAPI - La version** 3.0.0 ou supérieure est requise.
+ **Format de fichier** : format JSON uniquement (application/json).
+ **Limite de taille de fichier** : 1 Mo maximum pour l'ensemble de la spécification OpenAPI.
+ **Limite d'opérations** : au minimum 1 et au maximum 100 opérations d'API par connecteur.
### Champs de schéma obligatoires
Votre spécification OpenAPI doit inclure ces sections obligatoires.
**openapi**
La version d'OpenAPI utilisée (doit être « 3.0.0 » ou supérieure).
**info**
Informations sur le service, y compris le titre, la description et la version.
**serveurs**
URL de base et informations sur le serveur pour la connectivité aux API.
**chemins**
Définitions des points de terminaison d'API avec méthodes et opérations HTTP.
### Schémas d'authentification compatibles
Préparez les informations d'authentification en fonction des méthodes d'authentification prises en charge dans les spécifications OpenAPI.
**OAuth 2.0**
Prend en charge à la fois les flux d'octroi de code d'autorisation et d'octroi d'informations d'identification client. Nécessite les définitions d'AuthorizationURL, de tokenURL et de scopes dans le schéma de sécurité.
**Clé d'API**
Authentification par clé d'API transmise dans les paramètres de requête ou les en-têtes.
**Aucune authentification**
Option par défaut lorsqu'aucun schéma de sécurité n'est défini dans la spécification.
**Note**
Les schémas d'authentification non pris en charge dans la spécification OpenAPI seront ignorés et le connecteur utilisera par défaut l'absence d'authentification.
## Configurer l'intégration des spécifications OpenAPI
Après avoir préparé votre spécification OpenAPI et vos informations d'authentification, suivez ces étapes pour créer votre intégration de spécification OpenAPI.
1. Dans la console Amazon Quick, choisissez **Integrations.**
1. Cliquez sur **Ajouter** (plus le bouton « \$1 »).
1. Sur la page Ajouter un schéma, sélectionnez **Importer un schéma** et choisissez un schéma à importer.
1. Sélectionnez **Suivant**.
1. Renseignez les détails de l'intégration, y compris le nom et la description.
1. Passez en revue les actions disponibles générées à partir de votre spécification OpenAPI.
1. Sélectionnez **Créer et continuer**.
1. Choisissez les utilisateurs avec lesquels partager l'intégration.
1. Cliquez sur **Suivant**.
### Résultats attendus
Une fois la configuration réussie, l'intégration de votre spécification OpenAPI apparaît dans la liste des intégrations avec des actions générées dynamiquement en fonction de votre schéma. L'intégration peut être utilisée dans les flux de travail, les automatisations et les agents d'intelligence artificielle Amazon Quick, avec des tâches correspondant aux points de terminaison définis dans votre spécification OpenAPI.
## Exigences relatives au format et au modèle
Votre spécification OpenAPI doit respecter ces exigences de format.
+ **Modèles de trajectoire** - Doit suivre le modèle : `^/[^/]*(/[^/]*)*$` et commencer par une barre oblique (/).
+ **Fonctionnement IDs** - Doit suivre le schéma : `^[a-zA-Z0-9_ ]{1,256}$`
+ **Descriptions** : obligatoire pour toutes les opérations et tous les paramètres, 5 000 caractères maximum.
+ **Type de contenu** : seuls application/json les corps de demande et de réponse sont pris en charge.
## Fonctions non prises en charge
Les fonctionnalités OpenAPI suivantes ne sont pas prises en charge et peuvent provoquer des erreurs de validation.
+ **Types de tableaux** : les schémas comportant des types de tableaux (par exemple,`{"type": "array", "items": {"string"}}`) ne sont pas pris en charge.
+ **Mots-clés de composition** : les mots clés AllOf, OneOf, AnyOf et not ne sont pas pris en charge.
+ **Références circulaires - Les références** circulaires ou cycliques (\$1ref à l'intérieur de \$1ref) ne sont pas prises en charge.
+ **Structures imbriquées complexes** : évitez dans la mesure du possible les structures d'objets profondément imbriquées.
## Bonnes pratiques en matière de schéma
Suivez ces bonnes pratiques lors de la création de votre spécification OpenAPI.
### Rédigez des descriptions efficaces
Utilisez ces directives pour rédiger des descriptions claires et utiles.
+ **Descriptions des opérations** - Décrivez ce que fait l'opération, quand l'utiliser et comment elle se comporte.
+ **Descriptions des paramètres** : expliquez de manière concise l'objectif du paramètre et son impact sur le comportement des opérations.
+ **Contenu autonome** : assurez-vous que les descriptions fournissent des indications suffisantes, sans références externes.
+ **Clarté des dépendances** - Rendez les dépendances entre les opérations explicites dans les descriptions.
+ **Références d'**opérations : utilisez OperationID pour faire référence à d'autres opérations, et non à des chemins d'API.
### Recommandations relatives à la structure des paramètres
Structurez vos paramètres pour une utilisation optimale.
+ **Aplatir les objets complexes** : au lieu d'objets imbriqués, utilisez des paramètres distincts (par exemple, start\$1date, start\$1time, end\$1date, end\$1time).
+ **Utiliser des formats standard** - Utilisez des valeurs de format standard telles que « date-heure » ou « date » pour les dates et heures ISO-8601.
+ **Effacer les noms des paramètres** : utilisez des noms de paramètres descriptifs qui indiquent clairement leur objectif.
+ **Marquage des champs obligatoires** : marquez correctement les paramètres comme obligatoires ou facultatifs en fonction du comportement de l'API.
## Extensions prises en charge
Nous prenons en charge les extensions OpenAPI personnalisées pour améliorer l'expérience utilisateur.
**x-amzn-form-display-nom**
Utilisez-le au niveau du paramètre pour remplacer le nom de champ par défaut affiché dans les formulaires de confirmation. Actuellement pris en charge uniquement pour les paramètres du corps de la demande.
```
"x-amzn-form-display-name": "User Name"
```
**x-amzn-operation-type**
Définissez si une opération doit être traitée comme une « lecture » ou une « écriture ». Par défaut, les méthodes GET sont des opérations de « lecture » et toutes les autres méthodes HTTP sont des opérations d' « écriture ».
```
"x-amzn-operation-type": "read"
```
## Validation du schéma et gestion des erreurs
Lorsque vous téléchargez une spécification OpenAPI, nous effectuons une validation complète.
+ **Validation de la taille du fichier** : garantit que la spécification ne dépasse pas 1 Mo.
+ **Validation du nombre d'opérations** - Vérifie qu'entre 1 et 100 opérations sont définies.
+ **Validation de la structure du schéma** : vérifie si les champs sont obligatoires et si le formatage est correct.
+ **Validation du schéma de sécurité** : valide les méthodes d'authentification prises en charge.
+ **Validation du type de contenu** : garantit que seul application/json le contenu est utilisé.
Les erreurs de validation apparaissent sous l'éditeur de schéma et doivent être résolues avant que l'intégration puisse être créée. Les problèmes de validation courants incluent :
+ Champs obligatoires manquants (openapi, info, serveurs, chemins).
+ Modèles de chemin ou opération non valides IDs.
+ Fonctionnalités de schéma non prises en charge (tableaux, mots clés de composition).
+ Descriptions manquantes ou trop longues.
+ Références circulaires dans les définitions de schéma.
## Gérer l'intégration des spécifications OpenAPI
Après avoir créé l'intégration de votre spécification OpenAPI, vous pouvez la gérer à l'aide de plusieurs options.
### Partage l'intégration
Vous pouvez partager les connecteurs d'action OpenAPI Specification avec d'autres utilisateurs de votre organisation.
1. **Sur la page des détails de l'intégration d'OpenAPI, choisissez Partager.**
1. Configurez les options de partage :
+ **Partager avec des utilisateurs spécifiques** : entrez des noms d'utilisateur ou des adresses e-mail.
+ **Partager avec l'organisation** : mettez cette option à la disposition de tous les utilisateurs de votre organisation.
1. Définissez les niveaux d'autorisation pour l'accès partagé.
1. Choisissez **Partager l'intégration** pour appliquer les paramètres de partage.
### Supprimer l'intégration
Suivez ces étapes pour supprimer définitivement votre intégration OpenAPI.
1. **Sur la page des détails de l'intégration d'OpenAPI, choisissez Supprimer.**
1. Vérifiez l'impact de la suppression, y compris les flux de travail ou les automatisations utilisant cette intégration.
1. Entrez le nom de l'intégration pour confirmer la suppression.
1. Choisissez **Supprimer l'intégration** pour la supprimer définitivement.
## Résoudre les problèmes liés à l'intégration des spécifications OpenAPI
Utilisez ces conseils de dépannage pour résoudre les problèmes courants d'intégration de la spécification OpenAPI.
Erreurs de validation de schéma
Assurez-vous que votre spécification OpenAPI suit le bon format et inclut tous les champs obligatoires. Utilisez un validateur OpenAPI pour vérifier votre schéma avant de l'importer.
Aucune tâche générée
Vérifiez que votre spécification OpenAPI inclut les définitions de chemin avec les méthodes et les opérations HTTP. IDs Les actions sont générées en fonction des opérations définies dans votre schéma.
Authentication failures (Échecs d’authentification)
Vérifiez que le schéma d'authentification défini dans votre spécification OpenAPI correspond aux exigences réelles de l'API et que les informations d'identification sont correctement configurées.
Échec de l'exécution des actions
Vérifiez les paramètres d'action et assurez-vous qu'ils correspondent aux définitions des paramètres de votre spécification OpenAPI, y compris les champs et types de données obligatoires.