DataWorks:Tests, publication et gestion des versions d'une API

Tester une API en développement

Le test d'une API en développement s'effectue sur la page Service Development (environnement de développement). Avant de tester l'API, vous devez d'abord la générer en mode assistant ou en mode script, ou enregistrer un service existant en tant qu'API.

Procédure :

1. Connectez-vous à la console DataWorks. Dans la région cible, cliquez sur Data Analysis and Service > DataService Studio dans le volet de navigation de gauche. Sélectionnez un espace de travail dans la liste déroulante et cliquez sur Go to DataService Studio.

2. Dans la liste des API à gauche, double-cliquez sur le nom de l'API que vous souhaitez tester pour ouvrir sa page d'édition.

3. Sur la page d'édition de l'API, recherchez et cliquez sur le bouton Test pour ouvrir la boîte de dialogue Test APIs.

4. Dans le volet gauche de la boîte de dialogue, saisissez une valeur de test pour chaque paramètre de requête.

5. Cliquez sur Start Test pour déclencher l'appel d'API.

Afficher les résultats du test :

Une fois le test terminé, vous pouvez consulter les informations suivantes dans le volet droit de la boîte de dialogue :

• Request Details : Informations complètes de la requête pour l'appel d'API, y compris le chemin de requête, les en-têtes et le corps. Utilisez ces éléments pour vérifier que la structure de la requête est correcte.

• Response Details : Données de réponse renvoyées par l'API (le résultat de la requête réel). Comparez-les avec le résultat attendu pour vérifier que la logique de l'API est correcte.

• Response Duration : Latence de réponse de bout en bout de la requête API. Si la latence est élevée, envisagez d'optimiser la logique de requête ou la configuration de la source de données.

Si le test échoue, examinez attentivement le message d'erreur renvoyé, effectuez les modifications nécessaires et relancez le test.

Tester une API publiée

Le test d'une API publiée s'effectue sur la page Service Management (environnement de production). Cette opération permet de vérifier le comportement réel de l'API après sa publication. Avant d'effectuer ce test, vous devez d'abord publier l'API.

Procédure :

1. Sur la page Data Services , cliquez sur Service Management dans la barre de navigation supérieure.

2. Dans le volet de navigation de gauche, cliquez sur Test APIs.

3. Dans la liste déroulante, sélectionnez l'API que vous souhaitez tester et assurez-vous que les valeurs des paramètres de requête sont entièrement configurées.

4. Cliquez sur Start Test et consultez les sections Request Details et Response Details dans le volet droit.

Remarques :

• La page Test APIs fournit uniquement des fonctionnalités de test d'API en ligne. Elle ne permet pas de mettre à jour l'exemple de réponse normale d'une API.

• Si l'option Pagination for Return Results est configurée pour une API, le tri des données renvoyées dépend du comportement de la source de données sous-jacente. Si vous avez besoin d'un tri, vous pouvez configurer un Sort field pour l'API en mode assistant, ou ajouter une clause ORDER BY au code SQL en mode script.

Interprétation des résultats de test et suggestions d'optimisation

Un résultat de test d'API complet se compose de trois parties. Comprendre chaque partie vous aide à identifier rapidement les problèmes :

Lorsque les résultats du test sont conformes aux attentes, vous pouvez procéder à la publication de l'API sur API Gateway.

Prérequis

Avant de publier une API, assurez-vous que les conditions suivantes sont remplies :

• API Gateway est activé : Activez le service dans la console API Gateway.

  Important

  En raison des limitations de l'architecture réseau entre DataWorks et API Gateway, lors de l'achat d'une instance API Gateway, seules les instances dédiées traditionnelles sont prises en charge pour le paramètre Instance Type. Les instances intégrées au VPC ne sont pas prises en charge.

• Un groupe d'API est créé : Lors de la publication, l'API est déployée dans le groupe correspondant sur API Gateway en fonction de l'association au workflow. Assurez-vous que le workflow est correctement associé à un groupe API Gateway. Vous pouvez vérifier le nom du groupe en cliquant avec le bouton droit sur Workflow > Change.

Processus de publication

La publication d'API suit un processus en trois étapes : Soumission → Approbation → Publication :

Étape 1 : Soumettre l'API

1. Accédez à la page Data Services . Sur la page Service Development , double-cliquez sur le nom de l'API que vous souhaitez publier dans la liste des API pour ouvrir sa page d'édition.

2. Cliquez sur le bouton Submission en haut à droite.

3. Une fois la soumission réussie, le système génère automatiquement une version d'API (par exemple, V1 ou V2). Vous pouvez afficher l'état de la version dans le panneau Version qui apparaît à droite.

Étape 2 : Demander la publication et attendre l'approbation

1. Dans le panneau Version à droite, repérez la version d'API à publier et cliquez sur le bouton Publish.

2. Suivez les instructions à l'écran pour saisir le motif de la demande, puis cliquez sur Requested Permissions pour soumettre la demande de publication.

3. Si un processus d'approbation est configuré pour l'espace de travail, la demande de publication doit être approuvée dans le centre d'approbation. L'approbateur peut consulter les détails de la demande et traiter l'approbation sur la page Approval Center > To Be Processed.

4. Une fois l'approbation accordée, l'état de l'API dans le panneau Version passe de To Be Requested à Can Be Published.

Si aucun processus d'approbation n'est configuré pour l'espace de travail, vous pouvez passer directement à l'étape de publication après la soumission, sans attendre d'approbation. Pour plus d'informations, consultez Configurer un processus d'approbation.

Étape 3 : Exécuter la publication

1. Une fois l'approbation accordée, dans la barre de navigation droite de la page d'édition de l'API, cliquez sur Version et repérez la version d'API dont l'état est Can Be Published.

2. Cliquez sur le bouton Publish et attendez que le système indique que la publication a réussi.

3. Une fois l'API publiée, DataWorks la déploie dans le groupe correspondant sur API Gateway en fonction du groupe associé au workflow auquel l'API appartient.

Vérification post-publication

Après la publication, vous pouvez vérifier et gérer l'API de plusieurs façons :

• Affichage dans API Gateway : Connectez-vous à la console API Gateway . Consultez les informations de l'API publiée dans Manage APIs > Service List et configurez des politiques telles que la limitation du débit et le contrôle d'accès.

• Appels applicatifs : Si l'API est appelée par votre propre application, créez une application dans API Gateway, autorisez l'API pour cette application, puis utilisez AppKey et AppSecret pour des appels basés sur une signature chiffrée. API Gateway propose également des SDK pour les principaux langages de programmation. Pour plus d'informations, consultez Autoriser et appeler une API. Pour l'intégration du SDK, consultez Intégration du SDK.

• Modification du protocole : Pour une API publiée, sur l'onglet Service Management > Published APIs , cliquez sur More > Change Protocol pour l'API correspondante afin de modifier le protocole d'accès (par exemple, de HTTP à HTTPS). La modification du protocole prend effet immédiatement. Toutefois, si le protocole d'origine est supprimé, les appels d'API utilisant ce protocole échoueront. Procédez avec prudence.

Référencer sur Alibaba Cloud API Marketplace (facultatif)

Alibaba Cloud API Marketplace couvre plusieurs catégories et peut vous aider à monétiser vos données.

Une fois les API générées ou enregistrées dans Data Service publiées sur API Gateway, vous pouvez les référencer sur Alibaba Cloud API Marketplace en un clic, aidant ainsi les entreprises à monétiser la valeur de leurs données.

Prérequis :

• Seules les identités d'entreprise sont prises en charge pour l'inscription sur Alibaba Cloud API Marketplace.

• Avant le référencement, vous devez vous inscrire sur Alibaba Cloud Marketplace en tant que fournisseur de services. Pour connaître la procédure, consultez S'inscrire en tant que fournisseur de services.

Procédure :

1. Accédez à la plateforme des fournisseurs de services d'Alibaba Cloud.

2. Dans le volet de navigation de gauche, cliquez sur Commodity > Product Management.

3. Cliquez sur Publish Product.

4. Sur la page Access Information , configurez les paramètres selon les instructions (y compris le nom du produit, la stratégie de tarification et la liaison d'API) pour terminer le processus de référencement de l'API.

Afficher l'historique des versions

1. Connectez-vous à la console DataWorks. Dans la région cible, cliquez sur Data Analysis and Service > DataService Studio dans le volet de navigation de gauche. Sélectionnez un espace de travail dans la liste déroulante et cliquez sur Go to DataService Studio.

2. Sur la page Service Development , double-cliquez sur le nom de l'API que vous souhaitez consulter dans la liste des API pour ouvrir sa page d'édition.

3. Cliquez sur le bouton Version à droite de la page pour ouvrir le panneau des versions et afficher les informations et les détails des versions. Le panneau des versions affiche toutes les informations historiques des versions pour l'API actuelle, y compris :

   Remarque

   Chaque version propose un lien API Details dans la colonne Actions. Cliquez dessus pour afficher les informations de configuration complètes de cette version, y compris les paramètres de requête, les paramètres de réponse et la configuration de la source de données.

   Colonne	Description
   API ID	Identifiant unique de l'API actuelle.
   Version	Numéro de version, qui s'incrémente dans l'ordre de soumission (V1, V2, V3, etc.).
   Submitted By	Utilisateur ayant soumis cette version.
   Submitted At	Heure de publication de cette version, précise à la seconde près.
   Status	Publish (dernière version actuellement effective en ligne) Can Be Published (version ayant passé les tests et soumise) Batch Synchronization (ancienne version historique)

Comparaison des versions

Après plusieurs itérations d'une API, vous devrez peut-être comparer les versions pour comprendre les modifications spécifiques apportées.

Procédure :

1. Dans le panneau Version , sélectionnez deux versions quelconques que vous souhaitez comparer.

2. Cliquez sur le bouton Compare en bas du panneau.

3. Dans la boîte de dialogue History Version Contrast qui s'affiche, consultez les différences entre les deux versions.

Contenu de la comparaison :

• API en mode assistant : Affiche les différences dans les paramètres de requête et de réponse, y compris les modifications apportées aux attributs tels que le nom du paramètre, le type et le caractère obligatoire du paramètre.

• API en mode script : Affiche les différences textuelles dans les scripts SQL, avec les lignes ajoutées, supprimées et modifiées mises en évidence.

La comparaison des versions est particulièrement utile dans les scénarios de collaboration en équipe, car elle aide les réviseurs à comprendre rapidement le contenu de chaque modification.

Retour à une version précédente

Lorsqu'une nouvelle version est anormale ou ne répond pas aux attentes, vous pouvez revenir à une version stable précédente de l'API.

Procédure :

1. Dans le panneau Version , repérez la version historique cible.

2. Cliquez sur le bouton Roll Back dans la colonne Actions de cette version.

3. Dans la boîte de dialogue Confirm Rollback qui s'affiche, cliquez sur Confirm.

Une fois le retour arrière terminé, la configuration de l'API est restaurée au contenu de la version historique sélectionnée et la version en ligne actuelle est mise à jour immédiatement. Nous vous recommandons d'utiliser la fonctionnalité de comparaison des versions pour confirmer la configuration de la version cible avant d'effectuer un retour arrière, afin d'éviter des modifications involontaires.

Stratégie de gestion des versions

De bonnes pratiques de gestion des versions peuvent réduire considérablement le risque d'incidents en production.

• Enregistrement des modifications : À chaque soumission, décrivez clairement les modifications et les raisons dans les notes de soumission afin que les membres de l'équipe puissent comprendre le contexte grâce à la comparaison des versions.

• Vérification par déploiement progressif : Pour les modifications majeures, nous vous recommandons de vérifier entièrement dans l'environnement de test avant de publier dans l'environnement de production.

• Retour rapide : Lorsqu'un problème est détecté en ligne, utilisez le retour à une version précédente pour restaurer le service en premier lieu, puis investiguez la cause racine. Le retour arrière est plus rapide que la modification et la republication, minimisant ainsi l'impact commercial.

• Nettoyage régulier : Pour les API inutilisées depuis longtemps, retirez-les et nettoyez-les rapidement afin de réduire la complexité de gestion et les risques de sécurité potentiels.

Flux de travail collaboratif pour les tests et la publication

Dans les scénarios de collaboration en équipe, le flux de travail suivant est recommandé :

1. Les développeurs créent et configurent l'API sur la page Service Development.

2. Les développeurs testent l'API dans l'environnement de développement pour vérifier les fonctionnalités.

3. Les développeurs soumettent l'API pour générer une nouvelle version et initier une demande de publication.

4. Les approbateurs examinent la demande de publication dans le centre d'approbation et peuvent utiliser la fonctionnalité de comparaison des versions pour visualiser les modifications.

5. Après approbation, les développeurs exécutent l'opération de publication finale.

6. Les opérateurs effectuent des tests en ligne et surveillent l'API publiée sur la page Service Management.

7. Si des problèmes sont détectés, restaurez rapidement l'API via un retour à une version précédente, ou retirez-la pour réparation.

Ce flux de travail aide les équipes à réaliser une gestion efficace du cycle de vie complet des API tout en garantissant la qualité des publications.

Limitations des exemples de réponse

La page d'édition d'API permet de définir un exemple de réponse normale pour afficher la structure des données de réponse attendues dans la documentation de l'API. Notez les points suivants :

• Aucune synchronisation automatique : Les résultats de test de la page de test d'API ne sont pas automatiquement mis à jour en tant qu'exemple de réponse normale. Vous devez modifier manuellement ou coller l'exemple de réponse sur la page d'édition de l'API.

• Limite de taille : L'exemple de réponse normale a une limite maximale de caractères. Si les données de l'exemple sont trop volumineuses (par exemple, contenant des centaines d'enregistrements), l'enregistrement peut échouer. Conservez uniquement 2 à 3 enregistrements types comme exemple.

• Prise d'effet après publication : Après avoir modifié l'exemple de réponse normale, vous devez resoumettre et publier l'API pour que les modifications prennent effet dans la documentation d'API Gateway.

Gestion des modifications de la structure des tables de la source de données

Lorsque la structure de la table de la source de données associée à une API change (comme l'ajout de colonnes, la suppression de colonnes ou la modification des types de colonnes), les API publiées ne détectent pas automatiquement ces modifications. Si elles ne sont pas traitées, les problèmes suivants peuvent survenir :

Procédure :

1. Accédez à la page d'édition de l'API et modifiez la configuration de l'API en fonction des modifications de la structure de la table.

   1. Mode assistant : Resélectionnez la table ; le système actualise automatiquement la liste des colonnes.

   2. Mode script : Modifiez manuellement les noms de colonnes ou le nom de la table dans l'instruction SQL.

2. Après avoir enregistré la configuration, relancez un test pour vérifier les modifications.

3. Soumettez et republiez l'API.

Pour les API en mode assistant, après le clonage, si la structure de la table associée à l'API d'origine a changé, l'API clonée peut toujours utiliser les anciennes informations de structure de table. Nous vous recommandons de revenir en mode assistant pour actualiser la configuration des colonnes après le clonage.