Teknologi platform-protokol panggilan API


API Platform Terbuka (TOP) dipanggil berdasarkan protokol HTTP (ISV) boleh terus menggunakan SDK rasmi yang disediakan oleh TOP (menyokong berbilang bahasa, termasuk pengkapsulan permintaan, penyulitan tandatangan, tafsiran respons dan pengoptimuman prestasi. dll.), atau anda boleh merangkum permintaan HTTP untuk panggilan mengikut protokol TOP Berikut ialah penjelasan terperinci tentang prinsip permintaan HTTP merangkum sendiri untuk panggilan API.

Proses panggilan

Mengikut protokol TOP: Isikan parameter> Susun permintaan HTTP> Dapatkan respons HTTP>

Entri panggilan


Alamat URL perkhidmatan untuk memanggil API Platform terbuka pada masa ini menyediakan 4 persekitaran untuk digunakan oleh ISV: persekitaran ujian kotak pasir, persekitaran ujian formal, persekitaran rasmi dan persekitaran luar negara.

Persekitaran ujian kotak pasir:

Persekitaran ujian untuk perisian ISV, yang boleh digunakan selepas aplikasi dibuat. Persekitaran ini menyediakan versi ringkas Taobao, menyokong panggilan API dalam kebanyakan senario Kebenaran dan trafik persekitaran kotak pasir adalah tidak terhad dan boleh digunakan secara bebas.
  • Persekitaran ujian formal: Persekitaran simulasi formal sebelum perisian ISV dilancarkan. Ia boleh digunakan selepas aplikasi berjaya dibuat. Persekitaran ini digunakan terutamanya untuk beberapa senario di mana ujian tidak dapat diselesaikan dalam kotak pasir Panggilan API adalah terhad kepada 5,000 kali/hari, bilangan pengguna yang dibenarkan ialah 5 dan API yang boleh dipanggil adalah konsisten dengan kebenaran dan keupayaan. daripada permohonan itu.
  • Persekitaran formal: Persekitaran yang digunakan selepas perisian ISV dilancarkan had adalah berkaitan dengan kategori aplikasi, seperti pasaran perkhidmatan mengehadkan panggilan API kepada 1 juta kali/hari.
  • Persekitaran luar negara: Persekitaran luar negara juga merupakan jenis persekitaran formal, terutamanya digunakan oleh ISV luar negara (negara Eropah dan Amerika) Bagi ISV luar negara, prestasi penggunaan persekitaran luar negara akan menjadi dua kali lebih tinggi daripada persekitaran domestik. Persekitaran panggilan
  • https://gw.api.tbsandbox.com/router/rest

    Persekitaran formal
http://gw.api.taobao.com/router/resthttps://eco.taobao com /router/resthttps://api.taobao.com/router/rest
Persekitaran luar negarahttp://api.taobao.com/router/rest

Parameter awam

Parameter yang mesti dihantar semasa memanggil mana-mana API Parameter awam yang disokong pada masa ini ialah:

ialah ialah AppKey yang diberikan kepada aplikasi oleh TOP. NoTiada ialah versi protokol NoNoNo ialah algoritma ringkasan ialah
Nama parameterJenis parameterAdakah ianya perlu
hod String
nama antara muka API. app_keyString这里要注意正式环境和沙箱环境的AppKey是不同的(包括AppSecret),使用时要注意区分;进入开放平台控制台“应用管理-概览” 和 “应用管理-沙箱环境管理”可分别查看正式环境及沙箱环境的AppKey、AppSecret
sessionString
Selepas kebenaran log masuk pengguna berjaya, TOP mengeluarkan maklumat kebenaran kepada aplikasi untuk butiran, sila klik di sini. Apabila label dokumen API ini menunjukkan: "Keizinan diperlukan", parameter ini mesti diluluskan "Keizinan tidak diperlukan", maka parameter ini tidak perlu diluluskan "Keizinan pilihan", maka parameter ini adalah pilihan; . 00. Pelayan API Taobao membenarkan ralat masa maksimum 10 minit untuk permintaan pelanggan. formatString
Format respons. Lalai ialah format xml, nilai pilihan: xml, json. vString
API, nilai pilihan: 2.0. partner_idString
ID Rakan Kongsi. target_app_keyString
AppKey sasaran yang dipanggil, hanya sah apabila API yang dipanggil disediakan oleh ISV pihak ketiga. simplifyBoolean
Sama ada hendak menggunakan format pulangan JSON yang dipermudahkan, hanya sah apabila format=json, nilai lalainya ialah: palsu. sign_methodString
tandatangan, nilai pilihan adalah: hmac, md5. tandaString
hasil tandatangan parameter input API Algoritma tandatangan merujuk kepada pengenalan di bawah.

Parameter Perniagaan

Selain parameter awam yang mesti disertakan dalam panggilan API, jika API itu sendiri mempunyai parameter peringkat perniagaan, ia juga mesti diluluskan. Sila rujuk dokumentasi API untuk parameter peringkat perniagaan setiap API .

Algoritma Tandatangan

Untuk mengelakkan gangguan yang berniat jahat oleh penggodam semasa proses panggilan API, sebarang panggilan API perlu membawa tandatangan Pelayan TOP akan mengesahkan tandatangan berdasarkan parameter permintaan Permintaan dengan tandatangan haram akan ditolak. TOP pada masa ini menyokong dua algoritma tandatangan: MD5 (sign_method=md5), HMAC_MD5 (sign_method=hmac Proses tandatangan umum adalah seperti berikut:

  • Untuk semua parameter permintaan API (termasuk parameter awam dan parameter perniagaan, kecuali untuk parameter tanda dan). byte[] jenis parameter), diisih mengikut susunan jadual kod ASCII nama parameter. Contohnya: foo=1, bar=2, foo_bar=3, foobar=4, susunan yang diisih ialah bar=2, foo=1, foo_bar=3, foobar=4.
  • Kumpul nama parameter yang diisih dan nilai parameter bersama-sama Mengikut contoh di atas, hasilnya ialah: bar2foo1foo_bar3foobar4.
  • Ekodkan rentetan yang dipasang ke dalam UTF-8, dan gunakan algoritma tandatangan untuk mencerna strim bait yang dikodkan. Jika anda menggunakan algoritma MD5, anda perlu menambah rahsia apl sebelum dan selepas rentetan yang dipasang, dan kemudian meringkaskannya, seperti: md5(secret+bar2foo1foo_bar3foobar4+secret) jika anda menggunakan algoritma HMAC_MD5, anda perlu mulakan algoritma ringkasan dengan rahsia apl , dan kemudian ringkaskan, seperti: hmac_md5(bar2foo1foo_bar3foobar4).
  • Gunakan perwakilan heksadesimal hasil strim bait yang diperoleh daripada ringkasan, seperti: hex("helloworld".getBytes("utf-8")) = "68656C6C6F776F726C64"

Nota: 1 MD5 dan kedua-duanya adalah HMAC_MD5 panjang algoritma digest dinyatakan dalam heksadesimal. Satu aksara perenambelasan boleh mewakili 4 bit, jadi panjang rentetan yang ditandatangani ditetapkan pada 32 aksara perenambelasan.

Kod contoh tandatangan JAVA

. . toArray(new String[0]);
Arrays.sort(keys);
// Langkah 2: Rentekan semua nama parameter dan nilai parameter bersama
StringBuilder query = new StringBuilder();
if (Constants.SIGN_METHOD_MD5 . sama dengan (Kaedah tanda)) {
                                                                               menggunakan menggunakan           menggunakan menggunakan menggunakan 's   melalui keluar melalui keluar melalui keluar melalui     ’ 's'' ‐ hingga ‐‐‐‐‐‐‐ sama (tandaKaedah)                                                                                           nilai)) {
pertanyaan .append(key).append(value);
}
}

}

// Langkah 3: Gunakan penyulitan MD5/HMAC
byte[] bait;
jika (Constants.SIGN_METHOD_HMAC.equals) {
Bytes = encryptHMAC(query.toString(), secret);
} else {
 query.append(rahsia);
 bait = encryptMD5(query.toString());
}

  // Langkah 4: Perduaan ditukar kepada Huruf Besar perenambelasan
return byte2hex(bait);
}

public static byte[] encryptHMAC(String data, String secret) membuang IOException {
byte[] bytes = null;
cuba {
Secret Key secretKey = new SecretKeySpeget (Constants.CHARSET_UTF8), "HmacMD5");
  Mac mac = Mac.getInstance(secretKey.getAlgorithm());
  mac.init(secretKey);
  bait = mac.doFinal(data.getBytes(Con stants .CHARSET) );
    } tangkap (GeneralSecurityException gse) {
        buang baru IOException(gse.toString());
    }
    bait pulangan;   kembali encryptMD5(data.getBytes( Constants.CHARSET_UTF8));
}
 
String statik awam byte2hex(byte[] bait) {
     StringBuilder sign = new StringBuilder();
    untuk (int i = 0; th i = 0; i tes  String hex = integer.tohexstring (bytes [i] & 0xff);
if (hex.length () == 1) {
sign.append ("0");
}
sign.append (hex.toupperCase ()) ;
    }
    return sign.toString();
}



































Kod Contoh Tandatangan C#

rentetan statik awam SignTopRequest(IDictionary<string, string> parameters, string secret, string signMethod)
{
// Langkah 1: Isih kamus dalam susunan abjad mengikut Key
IDictionary<string, string< sortedDictions< rentetan, rentetan>(parameter, StringComparer.Ordinal);
IEnumerator<KeyValuePair<rentetan, rentetan>> dem = sortedParams.GetEnumerator();

// Langkah 2: Rentetan semua nama parameter dan nilai parameter query = new StringBuilder ();
if (constants.sign_method_md5.equals (signMethod))
{
{query.append (rahsia);
}
sementara (dem.movenext ())
{
menggunakan menggunakan melalui keluar daripada 's  to off       ''' out'''''' out‐‐‐‐‐‐‐‐‐‐‐‐‐‐ bersama-sama '1' kepada d'em. Nilai semasa) ;
        }
    }

// Langkah 3: Gunakan penyulitan MD5/HMAC
bait[] bait;
jika (Constants.SIGN_METHOD_HMAC.Equals(signMethod)(signMethod)(pengkodan MD5/HMAC)
UTHMACMD baru Getcoding Bytes (rahsia));
         bait = hmac.ComputeHash(Encoding.UTF8.GetBytes(query.ToString()));
      }
                                                                                                                                                                                                                                                                                                                            bait =         Buat();
bait = md5. ToString()));
}

// Langkah 4: Tukar perduaan kepada huruf besar perenambelasan
Hasil StringBuilder = StringBuilder();
untuk (int i = 0; i < bytes.Length; i++)
{
          hasil. Tambah(bait[i].ToString("X2"));
                                                                                                                                                                                   hasil.

Contoh panggilan
Ambil taobao.item.seller.dapatkan panggilan sebagai contoh Langkah-langkah khusus adalah seperti berikut:


1. Tetapkan nilai parameter

Parameter awam:

="taoomet. seller.get"

app_key = "12345678"

session = "test"

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

format = "json"
  • = "json"
  • sign_method = "md5 "
  • Parameter perniagaan:
  • medan = "num_iid,title,nick,price,num"
  • num_iid = 11223344

  • app_key = "12345678 "

fields = "num_iid,title,nick,price,num" format = "json"

    method = "taobao.item.seller.get"
  • num_iid = 11223344"
  • ses
  • sign_method = "md5 "
  • timestamp = "2016-01-01 12:00:00"
  • v = "2.0"
  • 3. Sambungkan nama parameter dan nilai parameter

3. iid, tajuk, nick,price , numformatjsonmethodtaobao.item.seller.getnum_iid11223344sessiontestsign_methodmd5timestamp2016-01-01 12:00:00v2.0

sebagai rahsia dunia
hasil tandatangan ialah: hex (md5( helloworld+splicing in order Nama parameter yang baik dan nilai parameter + helloworld)) = "66987CB115214E59E6EC978214934FB8"

5 Pasang permintaan HTTP
Gunakan nilai utf-8 untuk parameter nama dan parameter encode (nama pesanan semua URL). parameter boleh sewenang-wenangnya, tetapi parameter tandatangan mesti disertakan ), dan kemudian mulakan permintaan melalui GET atau POST (termasuk parameter jenis byte[]), seperti:


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_iidprice%2C2 3344&tanda= 66987CB115214E59E6 EC978214934FB8

Nota

  • Semua pengekodan data permintaan dan tindak balas adalah dalam format UTF-8 Sila URL kodkan semua nama parameter dan nilai parameter dalam URL. Jika Jenis Kandungan permintaan adalah aplikasi/x-www-form-urlencoded, semua nilai parameter dalam Badan HTTP juga dikodkan URL jika ia berada dalam format berbilang bahagian/form-data, nilai parameter setiap medan borang tidak perlu dikodkan tetapi bahagian charset setiap medan borang perlu dinyatakan sebagai utf-8.
  • Apabila panjang URL yang dipasang oleh nama parameter dan nilai parameter kurang daripada 1024 aksara, anda boleh menggunakan GET untuk memulakan permintaan apabila jenis parameter mengandungi jenis bait[] atau URL permintaan yang dipasang terlalu panjang, anda mesti menggunakan POST untuk memulakan permintaan. Semua API boleh menggunakan POST untuk memulakan permintaan.
  • Jika anda perlu menguji dalam persekitaran kotak pasir, sila dapatkan app_key yang sepadan dengan persekitaran kotak pasir pada halaman pengurusan kotak pasir konsol aplikasi (biasanya app_key bagi persekitaran rasmi didahului dengan "10") dan app_secret, dan nilai sesi yang sepadan juga Keizinan diperoleh dengan log masuk dengan akaun kotak pasir Keizinan persekitaran kotak pasir adalah serupa dengan kebenaran persekitaran formal untuk butiran, sila rujuk pengenalan kebenaran pengguna.
  • Menjana tandatangan hanya diperlukan apabila membuat panggilan API tanpa menggunakan SDK rasmi TOP Jika SDK rasmi TOP digunakan, SDK akan melengkapkan langkah ini secara automatik.

Soalan Lazim

Ralat tandatangan "Tandatangan tidak sah" telah dilaporkan semasa memanggil antara muka