プラットフォーム技術 - API呼び出しプロトコル


オープン プラットフォーム (TOP) の API は HTTP プロトコルに基づいて呼び出され、開発者 (ISV) は TOP が提供する公式 SDK (リクエストのカプセル化、署名の暗号化、レスポンスの説明などの多言語をサポート) を直接使用できます。 、パフォーマンスの最適化など) を呼び出して呼び出すことも、TOP プロトコルに従って呼び出しの HTTP リクエストをカプセル化することもできます。以下では、API 呼び出しの HTTP リクエストを自己カプセル化する原理について詳しく説明します。

呼び出しプロセス

TOP プロトコルによると: パラメータの入力> 署名の生成> HTTP リクエストの組み立て> HTTP リクエストの開始> HTTP レスポンスの取得> json/xml 結果の解釈、以下は一般的な図式です。呼び出しプロセスの図:


呼び出しエントリ ポイント

API を呼び出すためのサービス URL アドレスオープン プラットフォームは現在、ISV が使用できる 4 つの環境を提供しています。サンドボックステスト環境、フォーマルテスト環境、フォーマル環境、海外環境。

  • サンドボックス テスト環境: ISV ソフトウェアのテスト環境。アプリケーションの作成後に使用できます。この環境は、淘宝網の簡素化されたバージョンを提供し、ほとんどのシナリオで API 呼び出しをサポートします。サンドボックス環境のアクセス許可とトラフィックは無制限で、自由に使用できます。
  • 正式なテスト環境: ISV ソフトウェアを起動する前の正式なシミュレーション環境であり、アプリケーションが正常に作成された後に使用できます。この環境は主に、サンドボックスでテストを完了できない一部のシナリオで使用されます。API 呼び出しは 1 日あたり 5,000 回に制限され、許可されたユーザーの数は 5 で、呼び出すことができる API は権限と機能に一致します。アプリケーションの。
  • 正式環境: ISV ソフトウェアがオンラインになった後に使用される環境。この環境への入り口は正式なテスト環境と同じですが、アプリケーションがオンラインになった後はトラフィック制限がかかります。特定のトラフィック制限はアプリケーションに関連しています。アプリケーションが属するカテゴリによって異なります。たとえば、サービス マーケット アプリケーションの場合、API 呼び出しは 1 日あたり 100 万回に制限されます。
  • 海外環境: 海外環境も正式環境の一種で、主に海外(欧米諸国)の ISV で利用されています。海外 ISV の場合、海外環境の利用実績となります。国内環境よりも2倍も高くなります。

#呼び出し環境サービス アドレス (HTTP)サービス アドレス (HTTPS)サンドボックス環境http://gw.api.tbsandbox.com/router/resthttps:// gw .api.tbsandbox.com/router/restフォーマル環境http://gw.api.taabao.com/router/resthttps://eco.taobao.com/router/rest海外環境http://api.taabao.com/router/resthttps://api.taabao.com/router/rest

パブリック パラメータ

API を呼び出すときに渡す必要があるパラメータ。現在サポートされているパブリック パラメータは次のとおりです:

#パラメータの説明メソッド##文字列 は API インターフェイス名です。 app_keyString は、 によってアプリケーションに割り当てられた AppKey です。 sessionStringNoユーザーログイン認証 成功後、TOP はアプリケーションに対して認証情報を発行します。この API ドキュメントのラベルが次のように示している場合: 「認可が必要」の場合はこのパラメータを渡す必要があり、「認可が不要」の場合はこのパラメータを渡す必要はありません。「オプションの認可」の場合はこのパラメータはオプションです。 timestampString は、yyyy-MM-dd HH:mm:ss 形式の タイムスタンプです。タイムゾーンは GMT 8 です (例: 2016-01-01 12:00:00)。 Taobao API サーバーでは、クライアント リクエストの最大 10 分の時間エラーが許容されます。 StringStringStringStringBooleanStringString
パラメータ名パラメータの種類#必須ですか?
ここで注意すべきは、正式環境とサンドボックス環境の AppKey は異なります (AppSecret も含む) ので、使用する場合は区別に注意する必要があり、オープン プラットフォーム コンソールの「アプリケーション管理 - 概要」に入り、 「アプリケーション管理-サンドボックス環境管理」で正式環境とサンドボックス環境のAppKeyとAppSecretをそれぞれ確認します
#format
No応答形式。デフォルトは xml 形式で、オプションの値は xml、json です。 v
API プロトコルのバージョン、オプションの値: 2.0。 partner_id
Noパートナー ID。 target_app_key
No呼び出されるターゲット AppKey (呼び出される API がサードパーティによって提供される場合のみ) ISV は有効です。 simplify
No簡素化された JSON 戻り形式を使用するかどうか、format=json の場合のみ有効、デフォルト値は: false。 sign_method
は、 署名のダイジェスト アルゴリズムです。オプションの値は、hmac、md5 です。 sign
API 入力パラメータの署名結果です。署名アルゴリズムについては、以下の概要を参照してください。 。

ビジネス パラメータ

API 呼び出しに含める必要があるパブリック パラメータに加えて、API 自体にビジネス レベルのパラメータがある場合は、それらも渡す必要があります。ビジネスの API ドキュメントを参照してください。各 API の -level パラメータ。

署名アルゴリズム

API 呼び出しプロセス中のハッカーによる悪意のある改ざんを防ぐために、すべての API 呼び出しには署名が必要です。TOP サーバーはリクエスト パラメーターに基づいて署名を検証します。署名は不正です。要求は拒否されます。 TOP は現在 2 つの署名アルゴリズムをサポートしています: MD5 (sign_method=md5)、HMAC_MD5 (sign_method=hmac) 一般的な署名プロセスは次のとおりです:

  • すべての API リクエスト パラメーター (パブリック パラメーターとビジネス パラメーターを含む) ) 、ただし符号パラメータと byte[] 型パラメータは除きます)、パラメータ名の ASCII コード テーブルの順序に従ってソートされます。例: foo=1、bar=2、foo_bar=3、foobar=4、ソート順は bar=2、foo=1、foo_bar=3、foobar=4 です。
  • ソートされたパラメータ名とパラメータ値をまとめます。上記の例に従って得られる結果は、bar2foo1foo_bar3foobar4 です。
  • 組み立てられた文字列を UTF-8 にエンコードし、署名アルゴリズムを使用してエンコードされたバイト ストリームをダイジェストします。 MD5 アルゴリズムを使用する場合は、アセンブルされた文字列の前後にアプリのシークレットを追加し、次のように要約する必要があります: md5 (secret bar2foo1foo_bar3foobar4 secret); HMAC_MD5 アルゴリズムを使用する場合は、アプリのシークレットを使用したダイジェスト アルゴリズム、次にダイジェスト (hmac_md5(bar2foo1foo_bar3foobar4) など)。
  • サマリーから取得したバイト ストリーム結果の 16 進表現を使用します。例: hex("helloworld".getBytes("utf-8")) = "68656C6C6F776F726C64"
注: MD5 と HMAC_MD5 はどちらも 128 ビットのダイジェスト アルゴリズムであり、16 進数で表されます。1 つの 16 進文字は 4 ビットを表すことができるため、署名付き文字列の長さは 32 の 16 進文字に固定されます。

JAVA 署名サンプル コード

##public static String SignTopRequest(Map<String, String> params, String Secret, String SignMethod) throws IOException {
// ステップ 1: パラメーターがソートされているかどうかを確認する
String[] key = params.keySet().toArray(new String[0]);
Arrays.sort(keys);

// ステップ 2: すべてのパラメータ名とパラメータ値を一緒に文字列化する
StringBuilder query = new StringBuilder();
if (Constants.SIGN_METHOD_MD5.equals(signMethod)) {
query.append(secret);
}
for (String key:keys) {
使用して使用して使用します - spule out out out out out out out out out out out out out out out out out out out out out out out out out out out out out out out out outを使用して使用を使用して使用します
## ## // ステップ 3: MD5/HMAC 暗号化を使用する
byte[] bytes;
if (Constants.SIGN_METHOD_HMAC.equals(signMethod)) {
bytes = encryptHMAC (query.toString(), Secret) ;
} else {
query.append(secret);
bytes = encryptMD5(query.toString());
}

// ステップ 4: バイナリを大文字に変換する16 進数
return byte2hex(bytes);
}

public static byte[] encryptHMAC(String data, String Secret) throws IOException {
byte[] bytes = null;
try {
SecretKey SecretKey = new SecretKeySpec(secret.getBytes(Constants.CHARSET_UTF8), "HmacMD5");
Mac mac = Mac.getInstance(secretKey .getAlgorithm());
mac.init(secretKey) ;
バイト = mac.doFinal(data.getBytes(Constants.CHARSET_UTF8));
} catch (GeneralSecurityException gse) {
throw new IOException(gse.toString());
}
return bytes;
}

public static byte[] encryptMD5(String data ) throws IOException {
return 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# 署名サンプル コード


public static string SignTopRequest(IDictionary<string, string>parameters, string secret, string SignMethod)
{
// ステップ 1: Key によって辞書をアルファベット順に並べ替えます
IDictionary< ; string, string>sortedParams = new SortedDictionary<string, string>(parameters, StringComparer.Ordinal);
IEnumerator<KeyValuePair<string, string>> dem =sortedParams.GetEnumerator();

/ /ステップ 2: すべてのパラメーター名とパラメーター値を一緒に文字列化する
StringBuilder query = new StringBuilder();
if (Constants.SIGN_METHOD_MD5.Equals(signMethod))
{
query.Append( Secret );
}
while (dem.MoveNext())
{
文字列キー = dem.Current.Key;
文字列値 = dem.Current.Value;
if ( !string.IsNullOrEmpty(key) && !string.IsNullOrEmpty(value))
// ステップ 3: MD5/HMAC 暗号化を使用する
byte[] bytes;
if (Constants.SIGN_METHOD_HMAC.Equals(signMethod) )
{
HMACMD5 hmac = new HMACMD5(Encoding.UTF8.GetBytes(secret));
bytes = hmac.ComputeHash(Encoding.UTF8.GetBytes(query.ToString()));
}
else
{
query.Append(secret) ;
ステップ: バイナリを大文字の 16 進数に変換します
StringBuilder result = new StringBuilder();
for (int i = 0; i {
result.Append(bytes[i].ToString("X2"));
}

return result.ToString();
}


他の言語の署名サンプル コードについては、TOP 公式 SDK ソース コードを参照してください。

呼び出し例

taabao.item.seller.get 呼び出しを例として、具体的な手順は次のとおりです:

1. パラメータ値を設定します

パブリックパラメータ:

  • method = "taabao.item.seller.get"
  • app_key = "12345678"
  • session = "テスト"
  • timestamp = "2016-01-01 12:00:00"
  • format = "json"
  • v = "2.0"
  • sign_method = "md5 ”

ビジネスパラメータ:

  • fields = “num_iid,title,nick,price,num”
  • num_iid = 11223344

2. ASCII 順に並べ替えます

  • app_key = “12345678”
  • fields = “num_iid,title,nick,price, num”
  • format = “json”
  • method = “taabao.item.seller.get”
  • num_iid = 11223344
  • session = “テスト”
  • sign_method = "md5"
  • timestamp = "2016-01-01 12:00:00"
  • v = "2.0"

3. Splice パラメータ名とパラメータ値

##app_key12345678fieldsnum_iid,title,nick,price,numformatjsonmethodtaabao.item.seller.getnum_iid11223344sessiontestsign_methodmd5timestamp2016-01-01 12: 00:00v2 .0

4. 署名の生成 アプリのシークレットが helloworld であると仮定すると、署名の結果は次のようになります: hex( md5(helloworld) 適切なパラメータ名とパラメータ値の順序で結合されます helloworld)) = “66987CB115214E59E6EC978214934FB8”

5. HTTP リクエストを組み立てますUse utf-8 toすべてのパラメータ名とパラメータ値を URL エンコードし (パラメータの順序はオプションですが、署名パラメータを含める必要があります)、次のように GET または POST (byte[] タイプのパラメータを含む) を通じてリクエストを開始します。

http://gw.api.taabao.com/router/rest?method=taabao.item.seller.get&app_key=12345678&session=test×tamp=2016-01-01 12:00:00&format=json&v =2.0&sign_method=md5&fields=num_iid,title,nick,price, num&num_iid=11223344&sign=66987CB115214E59E6EC978214934FB8
##

注意事項

  • すべてのリクエストおよびレスポンス データのエンコードは UTF-8 形式であるため、URL 内のすべてのパラメータ名とパラメータ値を URL エンコードしてください。リクエストの Content-Type が application/x-www-form-urlencoded の場合、HTTP ボディ内のすべてのパラメータ値も URL エンコードされます。multipart/form-data 形式の場合、パラメータ値は各フォームフィールドの文字セット部分はエンコードする必要はありませんが、各フォームフィールドの文字セット部分はutf-8として指定する必要があります。
  • パラメータ名とパラメータ値で組み立てられた URL の長さが 1024 文字未満の場合、パラメータ タイプに byte[] タイプが含まれる場合、または組み立てられたリクエスト URL が次の場合、GET を使用してリクエストを開始できます。長すぎる場合は、POST を使用してリクエストを開始する必要があります。すべての API は POST を使用してリクエストを開始できます。
  • サンドボックス環境でテストする必要がある場合は、アプリケーションコンソールのサンドボックス管理ページでサンドボックス環境に対応したapp_keyを取得してください(通常は正式環境のapp_keyの前に「10」が付加されます) ) と app_secret に対応します セッション値も、サンドボックス アカウントのログイン認証を通じて取得されます。サンドボックス環境の認証は、正式な環境の認証に似ています。詳細については、ユーザー認証の概要を参照してください。
  • 署名 (サイン) の生成は、TOP 公式 SDK を使用せずに API 呼び出しを行う場合にのみ必要です。TOP 公式 SDK を使用する場合、このステップは SDK によって自動的に完了します。

FAQ

インターフェイス呼び出しで署名エラー「無効な署名」が報告される