Intégration des spécifications OpenAPI - Amazon Quick
Actions possiblesAvant de commencerPréparation de la spécification et de l'authentification OpenAPIConfigurer l'intégration des spécifications OpenAPIExigences relatives au format et au modèleFonctions non prises en chargeBonnes pratiques en matière de schémaExtensions prises en chargeValidation du schéma et gestion des erreursGérer l'intégration des spécifications OpenAPIRésoudre les problèmes liés à l'intégration des spécifications OpenAPI

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.

  2. Cliquez sur Ajouter (plus le bouton « + »).

  3. Sur la page Ajouter un schéma, sélectionnez Importer un schéma et choisissez un schéma à importer.

  4. Sélectionnez Suivant.

  5. Renseignez les détails de l'intégration, y compris le nom et la description.

  6. Passez en revue les actions disponibles générées à partir de votre spécification OpenAPI.

  7. Sélectionnez Créer et continuer.

  8. Choisissez les utilisateurs avec lesquels partager l'intégration.

  9. 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 ($ref à l'intérieur de $ref) 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_date, start_time, end_date, end_time).

  • 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.

  2. 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.

  3. Définissez les niveaux d'autorisation pour l'accès partagé.

  4. 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.

  2. Vérifiez l'impact de la suppression, y compris les flux de travail ou les automatisations utilisant cette intégration.

  3. Entrez le nom de l'intégration pour confirmer la suppression.

  4. 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.