Prérequis : trois éléments essentiels

Avant d'appeler toute API Data Service, vous devez remplir trois conditions préalables :

La relation entre ces trois éléments peut se résumer ainsi : l'API est la « porte », l'application est la « carte d'identité » et l'autorisation est le « laissez-passer ». Vous ne pouvez franchir la porte que si vous présentez à la fois une carte d'identité valide et le laissez-passer correspondant.

Créer une application (identité de l'application)

Une application sert de conteneur pour les identifiants d'appel d'API. Chaque application possède son propre jeu d'informations d'authentification (AppKey, AppSecret et AppCode), équivalent à un nom d'utilisateur et un mot de passe.

Application par défaut créée automatiquement

Lorsque vous publiez une API dans DataWorks pour la première fois, le système crée automatiquement une application portant le même nom que l'espace de travail dans API Gateway et autorise toutes les API de cet espace de travail pour cette application par défaut. Cela signifie que :

• Les membres de l'espace de travail peuvent utiliser les identifiants de l'application par défaut pour appeler les API sans avoir besoin d'une autorisation supplémentaire.

• Les informations d'authentification de l'application par défaut sont consultables sur la page Call APIs de la console Data Service.

Créer manuellement une application

Pour isoler le trafic ou différencier les autorisations selon les différents appelants, créez une nouvelle application dans la console API Gateway :

1. Connectez-vous à la console API Gateway.

2. Dans le volet de navigation de gauche, sélectionnez Application Management.

3. Cliquez sur Create Application et saisissez le nom et la description de l'application.

4. Une fois l'application créée, le système génère un ensemble d'AppKey, d'AppSecret et d'AppCode pour celle-ci.

Créez des applications distinctes pour différents scénarios d'appel (tels que les systèmes internes, les partenaires tiers et les tableaux de bord) afin de simplifier la surveillance du trafic, la limitation du débit et la gestion des autorisations.

Processus d'autorisation

L'autorisation accorde à une application la permission d'appeler une API spécifique. Seule une application autorisée peut appeler avec succès l'API correspondante en utilisant ses identifiants.

Accorder l'accès à d'autres comptes

Pour rendre une API disponible pour les espaces de travail sous d'autres comptes Alibaba Cloud, effectuez une autorisation inter-comptes :

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. Accédez à la page Data Services, cliquez sur Service Management dans la barre de menu supérieure, puis accédez à la page Manage APIs.

3. Sous l'onglet Published APIs, localisez l'API cible et cliquez sur Authorization dans la colonne Actions.

4. Dans la boîte de dialogue API Authorization, configurez les paramètres suivants :

   

   Paramètre	Description
   API Name	Nom de l'API à autoriser. Cette valeur ne peut pas être modifiée.
   Alibaba Cloud Account ID to Authorize	ID du compte Alibaba Cloud auquel il convient d'accorder l'autorisation d'appeler cette API. Vous pouvez consulter l'ID du compte sur la page .
   Authorized Workspace	Sélectionnez l'espace de travail sous le compte Alibaba Cloud cible.
   Authorization Validity Period	Sélectionnez la période de validité de l'autorisation (voir les détails ci-dessous).

5. Cliquez sur Confirm pour finaliser l'autorisation.

Période de validité de l'autorisation

La période de validité de l'autorisation détermine la durée pendant laquelle la partie autorisée peut appeler l'API :

Si une API autorisée est retirée du déploiement ou supprimée, la partie autorisée ne peut plus l'appeler. Si une API autorisée est retirée du déploiement puis republiée, ou modifiée et republiée, le propriétaire de l'API doit réautoriser la nouvelle version.

Consulter les API autorisées et accordées

Sur la page Manage APIs, vous pouvez afficher l'état des autorisations sous deux angles :

Afficher les API qui vous sont autorisées (quelles API suis-je autorisé à utiliser)

Cliquez sur l'onglet Authorized to Use pour afficher toutes les API que d'autres comptes vous ont autorisées. Sur cette page, vous pouvez :

• Cliquez sur Test pour tester une API autorisée en ligne. Pour plus d'informations, consultez la rubrique Tester une API.

• Cliquez sur Delete pour renoncer volontairement à l'autorisation d'appel d'une API.

Afficher les API que vous avez autorisées pour d'autres (quelles API ai-je autorisées pour d'autres)

Cliquez sur l'onglet Authorize Others to Use pour afficher les API que vous avez autorisées pour d'autres espaces de travail. Sur cette page, vous pouvez :

• Cliquez sur Test pour tester une API autorisée en ligne.

• Cliquez sur Manage pour révoquer ou modifier l'autorisation pour un espace de travail spécifique.

Trois scénarios d'autorisation

La granularité de l'autorisation des API varie en fonction de la taille de l'équipe et des exigences de sécurité. Les trois scénarios suivants couvrent les approches les plus courantes.

Scénario 1 : Même espace de travail, partage d'une seule application

Description du scénario : Tous les membres d'un même espace de travail DataWorks partagent l'application par défaut créée automatiquement pour l'espace de travail afin d'appeler les API.

Situation applicable : Petite équipe avec un niveau de confiance mutuelle élevé ; aucune nécessité de différencier le trafic d'appel par membre individuel ; démarrage rapide avec une configuration minimale.

Fonctionnement : Lorsqu'une API est publiée, DataWorks crée automatiquement une application portant le même nom que l'espace de travail et autorise toutes les API de l'espace de travail pour cette application. Tous les membres de l'espace de travail partagent les mêmes AppKey, AppSecret et AppCode.

Avantage : Zéro configuration, prêt à l'emploi. Inconvénient : Impossible d'identifier quel membre spécifique a initié un appel ; en cas de fuite des identifiants, tout l'espace de travail est affecté.

Scénario 2 : Chaque utilisateur RAM utilise une application indépendante

Description du scénario : Chaque utilisateur RAM (sous-compte) de l'organisation crée une application indépendante dans API Gateway et est individuellement autorisé à appeler les API.

Situation applicable : Nécessité de suivre précisément le comportement d'appel d'API de chaque utilisateur ; nécessité de définir des politiques de limitation différentes pour différents utilisateurs ; exigences élevées en matière de sécurité et de conformité imposant des identifiants par utilisateur.

Fonctionnement : Chaque utilisateur RAM se connecte à la console API Gateway et crée sa propre application ; l'administrateur de l'API autorise l'API individuellement pour l'application de chaque utilisateur ; chaque utilisateur appelle l'API en utilisant les identifiants de sa propre application.

Avantage : Le comportement d'appel est traçable au niveau individuel, l'isolation de sécurité est forte et l'impact d'une fuite d'identifiants est minimal. Inconvénient : Charge de gestion plus élevée ; chaque nouvel utilisateur nécessite la création d'une application et la configuration de l'autorisation.

Scénario 3 : Plusieurs utilisateurs RAM regroupés, chaque groupe partageant une application

Description du scénario : Plusieurs utilisateurs RAM sont divisés en groupes par fonction métier ou équipe, et les membres de chaque groupe partagent la même application pour appeler les API.

Situation applicable : Grande équipe organisée par département ou projet ; nécessité de différencier le trafic d'appel par ligne métier sans nécessiter de suivi par utilisateur ; équilibre entre coût de gestion et sécurité.

Fonctionnement : Créez un nombre correspondant d'applications pour chaque groupe métier ; l'administrateur de l'API autorise l'API pour l'application de chaque groupe ; les membres d'un groupe partagent les identifiants de l'application de leur groupe.

Avantage : Granularité de gestion modérée qui distingue les sources métier sans surcharge excessive. Inconvénient : Impossible de différencier davantage les membres au sein d'un même groupe.

Recommandations de sélection de scénario

Trois types d'identifiants : Évitez la confusion

Data Service utilise trois types distincts d'identifiants d'authentification ayant des objectifs, des sources et des scénarios d'utilisation différents. Assurez-vous de bien les distinguer :

Résumé rapide : L'AccessKey sert à « se connecter aux sources de données », l'AppKey à « appeler les API » et RAM à « accéder à la console ». Chacun a un objectif différent et ne peut remplacer les autres.

Confusion 1 : « Mon appel d'API renvoie une erreur 403, mais j'ai les autorisations d'administrateur RAM » — Les autorisations RAM contrôlent les opérations de la console DataWorks, et non les autorisations d'appel d'API. Les autorisations d'appel d'API sont contrôlées par l'autorisation de l'application. Même si vous êtes administrateur RAM, vous avez toujours besoin de l'AppKey/AppSecret d'une application autorisée pour appeler une API.

Confusion 2 : « L'AccessKey configuré pour la source de données est-il le même que l'AppKey pour les appels d'API ? » — Non. L'AccessKey est utilisé par Data Service pour se connecter aux sources de données backend ; l'AppKey est utilisé par les appelants pour appeler les API. Ils sont complètement indépendants.

Confusion 3 : Que dois-je saisir dans le champ « Alibaba Cloud Account ID » sur la page d'autorisation ? — La page d'autorisation requiert l'ID du compte Alibaba Cloud (une valeur numérique), et non un nom d'utilisateur RAM ou une adresse e-mail de connexion. Pour l'obtenir, connectez-vous à la page Account Management et consultez l'ID du compte dans les paramètres de sécurité.

Comparaison des méthodes d'authentification

API Gateway prend en charge deux méthodes d'authentification. Data Service ajoute par défaut l'« Authentification Alibaba Cloud APP » aux API de l'espace de travail. Choisissez une méthode en fonction de vos exigences de sécurité.

Authentification simple (AppCode)

Ajoutez l'AppCode à l'en-tête de la requête HTTP pour effectuer l'authentification. Aucun calcul de signature n'est requis.

Exemple de requête :

GET /api/v1/users?name=test HTTP/1.1
Host: your-api-endpoint.cn-shanghai.alicloudapi.com
Authorization: APPCODE 3f963a8e1cd7492bbd8a5e2e5e4c****

Authentification par signature (AppKey + AppSecret)

L'appelant utilise l'AppSecret pour calculer une signature HMAC-SHA256 sur le contenu de la requête et ajoute l'AppKey ainsi que la signature à l'en-tête de la requête. API Gateway recalcule la signature en utilisant le même AppSecret et la compare pour vérifier l'identité de l'appelant.

Exemple de requête (section en-tête) :

X-Ca-Key: 12345678
X-Ca-Signature: BASE64_ENCODED_SIGNATURE
X-Ca-Timestamp: 1741593600000
X-Ca-Nonce: unique-uuid-string
X-Ca-Signature-Headers: X-Ca-Key,X-Ca-Nonce,X-Ca-Timestamp

Comparaison des deux méthodes

Recommandations de sélection :

• Phase de développement et de test : Utilisez AppCode pour une vérification rapide des API afin de réduire les coûts de développement.

• Environnement de production : Utilisez toujours l'authentification par signature AppKey + AppSecret avec un chiffrement de transport HTTPS.

• API exposées en externe : L'utilisation de l'authentification par signature est obligatoire pour prévenir les attaques par rejeu après l'interception des identifiants lors de la transmission.

Détails de l'algorithme de signature

L'authentification par signature repose sur l'algorithme HMAC-SHA256. Le processus principal est le suivant :

Aperçu du processus de signature

1. Construire la chaîne de requête canonique (StringToSign) : Concaténez dans l'ordre la méthode HTTP (GET/POST), l'en-tête Accept, Content-MD5 (valeur MD5 du corps de la requête), Content-Type, Date, les en-têtes personnalisés impliqués dans la signature (X-Ca-*, triés par ordre alphabétique) et l'URL canonique (chemin + paramètres de requête triés).

2. Calculer la signature à l'aide de HMAC-SHA256 : Signature = Base64(HMAC-SHA256(AppSecret, StringToSign))

3. Ajouter les informations de signature à l'en-tête de la requête : Cela inclut X-Ca-Key (AppKey), X-Ca-Signature (valeur de la signature), X-Ca-Timestamp (horodatage en millisecondes), X-Ca-Nonce (UUID pour la protection contre les rejeux) et X-Ca-Signature-Headers (liste des en-têtes impliqués dans la signature).

Points clés à considérer

Les détails suivants sont des sources courantes d'erreurs de signature :

• Tri des paramètres : Les paramètres de requête URL et les en-têtes de signature doivent être triés par clé dans l'ordre alphabétique (ordre ASCII).

• Encodage URL : Les caractères spéciaux dans les valeurs des paramètres (espaces, caractères chinois, etc.) doivent être encodés en URL.

• Séparateur de ligne : Les lignes dans StringToSign doivent être séparées par \n (LF). N'utilisez pas \r\n (CRLF).

• Gestion des valeurs vides : En l'absence de corps, Content-MD5 est une chaîne vide (et non null). Lorsque des en-têtes tels que Accept n'existent pas, utilisez également une chaîne vide.

• Précision de l'horodatage : X-Ca-Timestamp est un horodatage en millisecondes. La différence de temps entre le client et le serveur ne doit pas dépasser 15 minutes.

• Unicité du nonce : Un UUID unique doit être généré pour chaque requête en tant que X-Ca-Nonce. La réutilisation d'un nonce déclenche l'interception d'attaque par rejeu.

Pour des exemples de code complets en Java et Python, les règles détaillées de concaténation de StringToSign et les méthodes de débogage des erreurs de signature courantes, consultez la section Algorithme de signature de la documentation API Gateway.

Consulter les identifiants d'authentification

Après avoir créé une application et obtenu l'autorisation, récupérez l'AppKey, l'AppSecret ou l'AppCode pour effectuer des appels d'API.

Consulter les identifiants depuis la console Data Service

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 Data Service, cliquez sur Service Management dans la barre de menu supérieure.

3. Dans le volet de navigation de gauche, cliquez sur Call APIs.

4. Sur la page Call APIs, vous pouvez afficher et copier les informations d'authentification suivantes : AppKey (identifiant unique de l'application), AppSecret (utilisé pour l'authentification par signature ; gardez-le sécurisé) et AppCode (utilisé pour l'authentification simple).

Consulter les identifiants depuis la console API Gateway : Connectez-vous à la console API Gateway, localisez l'application cible dans Application Management et accédez à la page des détails de l'application pour afficher l'AppKey, l'AppSecret et l'AppCode.

L'AppSecret et l'AppCode sont des informations sensibles. Ne les exposez pas dans les référentiels de code, les journaux, les pages frontend ou d'autres emplacements publics. Si vous suspectez une fuite d'identifiants, réinitialisez immédiatement l'AppSecret dans la console API Gateway.

Appeler des API à l'aide du SDK API Gateway

API Gateway fournit des SDK pour les langages de programmation principaux avec des implémentations intégrées de l'algorithme de signature. Il vous suffit de fournir l'AppKey et l'AppSecret. Pour plus d'informations, consultez les rubriques Appeler une API et Téléchargement et utilisation du SDK.

Langages SDK pris en charge

Avantages de l'utilisation du SDK

Par rapport à la construction manuelle de requêtes HTTP, le SDK offre les avantages suivants :

• Signature automatique : Le SDK implémente l'algorithme de signature HMAC-SHA256, ce qui dispense les développeurs de gérer les détails de la signature.

• Nouvelle tentative automatique : Certains SDK intègrent des mécanismes de nouvelle tentative en cas d'exceptions réseau.

• Validation des paramètres : Le SDK valide les paramètres avant d'envoyer les requêtes.

• Optimisation des performances : Les SDK utilisent généralement le pooling de connexions et HTTP/2 pour améliorer les performances réseau.

Exemple d'intégration rapide (Java)

L'exemple suivant montre comment appeler une API Data Service à l'aide du SDK Java API Gateway :

// 1. Add Maven dependency // <dependency> // <groupId>com.aliyun.api.gateway</groupId> // <artifactId>sdk-core-java</artifactId> // <version>latest version</version> // </dependency> // 2. Initialize the client HttpClientBuilderParams params = new HttpClientBuilderParams(); params.setAppKey("your_app_key"); params.setAppSecret("your_app_secret"); ApacheHttpClient client = new ApacheHttpClient(params); // 3. Construct the request IoTApiRequest request = new IoTApiRequest(); request.setDomain("your-api-endpoint.cn-shanghai.alicloudapi.com"); request.setPath("/api/v1/query"); request.setHttpMethod("GET"); request.putQueryParam("pageSize", "10"); request.putQueryParam("pageNum", "1"); // 4. Execute the call ApiResponse response = client.execute(request); System.out.println("Response: " + response.getBody());

Exemple d'intégration rapide (Python)

1. Install the SDK # pip install aliyun-api-gateway-sdk # 2. Call the API from com.alibaba.cloudapi.sdk.client import DefaultClient from com.alibaba.cloudapi.sdk.model import HttpClientBuilderParams params = HttpClientBuilderParams() params.app_key = "your_app_key" params.app_secret = "your_app_secret" params.host = "your-api-endpoint.cn-shanghai.alicloudapi.com" client = DefaultClient(params) response = client.get( path="/api/v1/query", query_params={"pageSize": "10", "pageNum": "1"}, headers={"Accept": "application/json"} ) print(f"Status: {response.status_code}") print(f"Body: {response.content}")

Pour des instructions d'utilisation détaillées, des références d'API et des exemples de code pour chaque SDK linguistique, consultez la section Téléchargement et utilisation du SDK de la documentation API Gateway.

Résumé du processus d'appel complet

Le processus complet, de la publication de l'API à l'appel réussi, se déroule comme suit : Le développeur d'API développe, teste et publie l'API sur API Gateway, qui crée automatiquement une application par défaut et l'autorisation associée. Pour le partage inter-comptes, le développeur autorise manuellement le compte cible. L'appelant d'API crée une application ou utilise l'application par défaut, obtient les identifiants (AppKey/AppSecret/AppCode), choisit une méthode d'authentification (AppCode pour l'authentification simple ou AppKey + AppSecret pour l'authentification par signature) et appelle l'API via le SDK ou HTTP. Après vérification de l'identité par API Gateway, Data Service exécute la requête et renvoie les résultats.

Références

• Publier une API : Découvrez comment publier une API sur API Gateway.

• Autoriser une API : Découvrez les opérations d'autorisation et la gestion des API autorisées pour d'autres.

• Tester une API : Testez les API publiées ou autorisées sur la page Service Management.