Protocole d'appel API de technologie de plate-forme


L'API de la plateforme ouverte (TOP) est appelée sur la base du protocole HTTP. Les développeurs (ISV) peuvent utiliser directement le SDK officiel fourni par TOP (prend en charge plusieurs langues, y compris l'encapsulation des requêtes, le cryptage des signatures, l'interprétation des réponses et l'optimisation des performances). etc.), ou vous pouvez encapsuler les requêtes HTTP pour les appels selon le protocole TOP. Voici une explication détaillée du principe de l'auto-encapsulation des requêtes HTTP pour les appels API.

Processus d'appel

Selon le protocole TOP : Remplir les paramètres> Générer la signature> Assembler la requête HTTP> Obtenir la réponse HTTP>

Entrée d'appel


Adresse URL du service pour appeler l'API. La plate-forme ouverte fournit actuellement 4 environnements que les éditeurs de logiciels indépendants peuvent utiliser : environnement de test sandbox, environnement de test formel, environnement officiel et environnement étranger.

Environnement de test Sandbox :

Un environnement de test pour les logiciels ISV, qui peut être utilisé après la création de l'application. Cet environnement fournit une version simplifiée de Taobao, prenant en charge les appels API dans la plupart des scénarios. Les autorisations et le trafic de l'environnement sandbox sont illimités et peuvent être utilisés librement.
  • Environnement de test formel : L'environnement de simulation formel avant le lancement du logiciel ISV. Il peut être utilisé une fois l'application créée avec succès. Cet environnement est principalement utilisé pour certains scénarios dans lesquels les tests ne peuvent pas être effectués dans le bac à sable. Les appels d'API sont limités à 5 000 fois/jour, le nombre d'utilisateurs autorisés est de 5 et les API pouvant être appelées sont cohérentes avec les autorisations et les capacités. de la demande.
  • Environnement formel : L'environnement utilisé après le lancement du logiciel ISV. L'entrée dans cet environnement est la même que l'environnement de test formel. Cependant, après le lancement de l'application, la limite de trafic sera activée. La limite est liée à la catégorie de l'application, comme le marché des services. Les applications de classe limitent les appels d'API à 1 million de fois/jour.
  • Environnement outre-mer : L'environnement outre-mer est également un type d'environnement formel, principalement utilisé par les éditeurs de logiciels indépendants d'outre-mer (pays européens et américains). Pour les éditeurs de logiciels indépendants d'outre-mer, les performances d'utilisation de l'environnement d'outre-mer seront deux fois plus élevées que celles de l'environnement d'outre-mer. environnement domestique.


Environnement d'appelAdresse de service (HTTP)Environnement sandboxhttp://gw.api.tbsandbox.com/router/rest http://gw.api.taobao.com/router/resthttp://api.taobao.com/router/rest
Adresse de service (HTTPS)
https://gw.api.tbsandbox.com/router/restEnvironnement formel
https://eco.taobao com. /router/restEnvironnement outre-mer
https://api.taobao.com/router/rest

Paramètres publics

Les paramètres qui doivent être transmis lors de l'appel d'une API sont les suivants :

Nom du paramètreType de paramètreEst-ce nécessaireDescription du paramètre
meth. oh String est le nom de l'interface API .
app_keyString est l'AppKey attribuée à l'application par TOP. 这里要注意正式环境和沙箱环境的AppKey是不同的(包括AppSecret),使用时要注意区分;进入开放平台控制台“应用管理-概览” 和 “应用管理-沙箱环境管理”可分别查看正式环境及沙箱环境的AppKey、AppSecret
sessionStringNonUne fois l'autorisation de connexion de l'utilisateur réussie, TOP transmet les informations d'autorisation à l'application. Pour plus de détails, veuillez cliquer ici. Lorsque le label de ce document API indique : « Autorisation requise », ce paramètre doit être passé ; « Autorisation non requise », alors ce paramètre n'a pas besoin d'être passé « Autorisation facultative », alors ce paramètre est facultatif.
timestampString est un horodatage , le format est aaaa-MM-jj HH:mm:ss, le fuseau horaire est GMT+8, par exemple : 01/01/2016 12h00 : 00. Le serveur API Taobao autorise une erreur de temps maximale de 10 minutes pour les demandes des clients.
formatChaîneNonFormat de réponse. La valeur par défaut est le format XML, valeurs facultatives : XML, JSON.
vString est la version du protocole API, valeur facultative : 2.0.
partner_idStringNoID du partenaire.
target_app_keyStringNoL'AppKey cible appelée, valide uniquement lorsque l'API appelée est fournie par un ISV tiers.
simplifyBooleanNonS'il faut utiliser le format de retour JSON simplifié, valable uniquement lorsque format=json, la valeur par défaut est : false.
sign_methodString est l'algorithme de résumé de signature, les valeurs facultatives sont : hmac, md5.
signString est le résultat de la signature du paramètre d'entrée API L'algorithme de signature fait référence à l'introduction ci-dessous.

Paramètres métier

En plus des paramètres publics qui doivent être inclus dans les appels d'API, si l'API elle-même possède des paramètres de niveau métier, ils doivent également être transmis. Veuillez vous référer à la documentation de l'API pour les paramètres de niveau métier de chaque API. .

Algorithme de signature

Afin d'éviter toute falsification malveillante par des pirates informatiques pendant le processus d'appel de l'API, tout appel d'API doit porter une signature. Le serveur TOP vérifiera la signature en fonction des paramètres de la demande. Les demandes avec des signatures illégales seront rejetées. TOP prend actuellement en charge deux algorithmes de signature : MD5 (sign_method=md5), HMAC_MD5 (sign_method=hmac). Le processus général de signature est le suivant :

  • Pour tous les paramètres de requête API (y compris les paramètres publics et les paramètres métier, à l'exception des paramètres de signature). et paramètres de type byte[]), triés selon l'ordre de la table de codes ASCII des noms de paramètres. Par exemple : foo=1, bar=2, foo_bar=3, foobar=4, l'ordre de tri est bar=2, foo=1, foo_bar=3, foobar=4.
  • Assemblez les noms de paramètres triés et les valeurs de paramètres. Selon l'exemple ci-dessus, le résultat est : bar2foo1foo_bar3foobar4.
  • Encodez la chaîne assemblée en UTF-8 et utilisez l'algorithme de signature pour digérer le flux d'octets codé. Si vous utilisez l'algorithme MD5, vous devez ajouter le secret de l'application avant et après la chaîne assemblée, puis le résumer, par exemple : md5(secret+bar2foo1foo_bar3foobar4+secret) ; initialisez l'algorithme de résumé avec le secret de l'application, puis résumez, tel que : hmac_md5(bar2foo1foo_bar3foobar4).
  • Utilisez une représentation hexadécimale du résultat du flux d'octets obtenu à partir du résumé, tel que : hex("helloworld".getBytes("utf-8")) = "68656C6C6F776F726C64"

Remarque : MD5 et HMAC_MD5 sont tous deux de 128 bits. La longueur de l'algorithme de résumé est exprimée en hexadécimal. Un caractère hexadécimal peut représenter 4 bits, la longueur de la chaîne signée est donc fixée à 32 caractères hexadécimaux.

Échantillon de code de signature JAVA

public static String signTopRequest(Map<String, String> params, String secret, String signMethod) lance IOException {
// Étape 1 : Vérifiez si les paramètres ont été triés
String[] keys = params.keySet() . toArray(new String[0]);
Arrays.sort(keys);

// Étape 2 : Chaîner tous les noms et valeurs de paramètres ensemble
Requête StringBuilder = new StringBuilder();
if (Constants.SIGN_METHOD_MD5 . est égal à (signMethod)) {
                                                                                               utiliser utiliser           utiliser utiliser utiliser utiliser 's   à travers à travers à travers à travers à travers à travers     ’ ’ ‐ à ‐‐‐‐‐‐ égal(signMethod))                                                                                             valeur)) {
requête .append(key).append(value);
}
}

}

// Étape 3 : Utiliser le cryptage MD5/HMAC
byte[] bytes;
if (Constants.SIGN_METHOD_HMAC.equals(signMethod)) {
Bytes = encryptHMAC(query.toString(), secret);
} else {
 query.append(secret);
 bytes = encryptMD5(query.toString());
}

  // Étape 4 : binaire converti en majuscules hexadécimal
return byte2hex(bytes);
}

public static byte[] encryptHMAC(String data, String secret) throws IOException {
byte[] bytes = null;
try {
Secret Key secretKey = new SecretKeySpec (secret.getBytes (Constants.CHARSET_UTF8), "HmacMD5");
  Mac mac = Mac.getInstance(secretKey.getAlgorithm());
  mac.init(secretKey);
  bytes = mac.doFinal(data.getBytes(Constants .CHARSET_UTF8) );
    } catch (GeneralSecurityException gse) {
        throw new IOException (gse.toString()); encryptMD5(data.getBytes( Constants.CHARSET_UTF8));
}
 
public static String byte2hex(byte[] bytes) {
    StringBuilder sign = new StringBuilder();
    for (int i = 0; i < bytes.length; i++) {
         String hex = Integer.toHexString(bytes[i] & 0xFF);
        if (hex.length() == 1) {
            sign.append("0");
        }
        sign.append(hex.toUpperCase()) ;
    }
    return sign.toString();
}




































C# Signature Exemple de code


chaîne statique publique SignTopRequest(IDictionary<string, string> paramètres, string secret, string signMethod)
{
// Étape 1 : Trier le dictionnaire par ordre alphabétique par clé
IDictionary<string, string> string, string>(parameters, StringComparer.Ordinal);
IEnumerator<KeyValuePair<string, string>> dem = sortedParams.GetEnumerator();

// Étape 2 : Enchaîner tous les noms et valeurs de paramètres
StringBuilder query = new StringBuilder ();                                                                        utiliser   utiliser   utiliser                   à travers   à l'extérieur out out out of  à  off       ''' out''''''' out-‐‐‐‐‐‐‐‐‐‐‐ ensemble's ensemble's'à d'em.Valeur actuelle ; ;
}
}

// Étape 3: Utilisez le cryptage MD5 / HMAC
octet [] octets;
if (constants.sign_method_hmac.equals (signalThod))
{
hmacmd5 hmac = new hmacmd5 (Encoding.Utf8.getcoding bytes bytes (secret));
         octets = hmac.ComputeHash(Encoding.UTF8.GetBytes(query.ToString()));
      }
                                                                                                                                                                                                                                 octets =         Create();
octets = md5. ToString()));
}

// Étape 4 : Convertir le binaire en hexadécimal majuscule
Résultat StringBuilder = new StringBuilder();
for (int i = 0; i < bytes.Length; i++)
{
          result.Append(bytes[i].ToString("X2"));
                                                                                                                                                             résultat.

Exemple d'appel
Prenons l'appel taobao.item.seller.get comme exemple. Les étapes spécifiques sont les suivantes :


1. Définir la valeur du paramètre

Paramètres publics :

method = "taobao.item. seller.get"

app_key = "12345678" session = "test"

timestamp = "2016-01-01 12:00:00"

    format = "json"
  • v = "2.0"
  • sign_method = "md5"
  • Paramètres commerciaux :
  • fields = "num_iid,title,nick,price,num"
  • num_iid = 11223344

2. = "12345678 "

    fields = "num_iid,title,nick,price,num"
  • format = "json"
  • method = "taobao.item.seller.get"

num_iid = 11223344session = "test"

    sign_method = "md5"
  • timestamp = "2016-01-01 12:00:00"
  • v = "2.0"
  • 3. Nom et valeur du paramètre d'épissure
  • app_key12345678fieldsnum_i identifiant, titre, nick,price , numformatjsonmethodtaobao.item.seller.getnum_iid11223344sessiontestsign_methodmd5timestamp2016-01-01 12:00:00v2.0

4. Générer une signature En supposant que le secret de l'application est helloworld, le résultat de la signature est : hexadécimal (md5( helloworld+splicing in order Bons noms de paramètres et valeurs de paramètres + helloworld)) = "66987CB115214E59E6EC978214934FB8"

5. Assembler la requête HTTP
Utilisez utf-8 pour encoder l'URL de tous les noms de paramètres et valeurs de paramètres (l'ordre de les paramètres peuvent être arbitraires, mais les paramètres de signature doivent être inclus), puis lancez une requête via GET ou POST (y compris les paramètres de type byte[]), telle que :

http://gw.api.taobao.com /router/rest?method=taobao.item.seller.get&app_key =12345678&session=test×tamp=2016-01-01+12%3A00%3A00&format=json&v=2.0&sign_method=md5&fields=num_iid%2Ctitle%2Cnick%2Cprice%2Cnum&num_iid=11223344& signe= 66987CB115214E59E6 EC978214934FB8

Notes

  • Tous les encodages des données de demande et de réponse sont au format UTF-8. Veuillez encoder tous les noms et valeurs de paramètres dans l'URL. Si le Content-Type de la requête est application/x-www-form-urlencoded, toutes les valeurs des paramètres dans le corps HTTP sont également codées en URL ; si elle est au format multipart/form-data, les valeurs des paramètres ; de chaque champ de formulaire n'a pas besoin d'être codé, mais la partie charset de chaque champ de formulaire doit être spécifiée en utf-8.
  • Lorsque la longueur de l'URL assemblée par le nom du paramètre et la valeur du paramètre est inférieure à 1024 caractères, vous pouvez utiliser GET pour lancer la requête ; lorsque le type de paramètre contient le type byte[] ou que l'URL de la requête assemblée est trop longue, vous doit utiliser POST pour lancer la demande. Toutes les API peuvent utiliser POST pour lancer des requêtes.
  • Si vous avez besoin de tester dans un environnement sandbox, veuillez vous procurer l'app_key correspondant à l'environnement sandbox sur la page de gestion sandbox de la console de l'application (généralement l'app_key de l'environnement officiel est précédée de "10") et app_secret, et le la valeur de session correspondante est également L'autorisation est obtenue en se connectant avec un compte sandbox. L'autorisation de l'environnement sandbox est similaire à l'autorisation formelle de l'environnement. Pour plus de détails, veuillez vous référer à l'introduction de l'autorisation utilisateur.
  • La génération d'une signature n'est requise que lors des appels API sans utiliser le SDK officiel TOP Si le SDK officiel TOP est utilisé, le SDK terminera automatiquement cette étape.

FAQ

L'appel d'interface signale une erreur de signature "Signature invalide"