Python调用1688商品详情API的实战示例与代码解析

前言

一、前置准备工作

在编写代码前，你必须完成以下步骤，否则无法正常调用 API：

1. 关注博主：完成企业 / 个人实名认证。
2. 创建应用并获取密钥 ：在开放平台创建应用，审核通过后获取 App Key 和 App Secret（核心身份凭证，需妥善保管，不要泄露）。
3. 申请商品详情 API 权限 ：在应用中申请「1688 商品详情查询」相关 API（如 alibaba.item.get），部分接口可能需要付费或满足平台资质要求。
4. 了解 API 参数与返回格式 ：查看官方文档，明确 API 的请求地址、必填参数（如商品 ID item_id）、请求方式（GET/POST）、签名规则（阿里 API 多采用 TOP 签名机制）。
5. 安装依赖库 ：Python 中需要用到 requests（发送 HTTP 请求）和 hmac、hashlib（生成 API 签名），执行安装命令：

bash

运行

pip install requests

二、核心知识点说明

1688 API 调用的核心难点是TOP 签名验证（阿里开放平台的接口安全机制），签名用于验证请求的合法性，防止请求被篡改。核心签名步骤：

• 整理所有请求参数（包括 App Key、时间戳、格式等公共参数 + 商品 ID 等业务参数）。
• 按参数名 ASCII 码升序排序，拼接成字符串。
• 用 App Secret 作为密钥，进行 HMAC-SHA1 加密，再进行 Base64 编码，得到签名（sign）。

三、完整实战代码

以下是 Python 调用 1688 商品详情 API（alibaba.item.get）的完整示例，包含签名生成、请求发送、响应解析：

python

运行

import requests
import time
import urllib.parse
import hmac
import hashlib
import base64

class Ali1688API:
    """1688开放平台API调用封装类，专注于商品详情查询"""
    def __init__(self, app_key, app_secret):
        """
        初始化函数
        :param app_key: 阿里开放平台应用App Key
        :param app_secret: 阿里开放平台应用App Secret
        """
        self.app_key = app_key
        self.app_secret = app_secret
        # 1688 API公共请求地址（TOP网关）
        self.gateway_url = "https://gw.open.1688.com/openapi/http/1/system.oauth2/getToken"
        self.item_detail_url = "https://gw.open.1688.com/openapi/http/1/alibaba.item.get"
    
    def _generate_sign(self, params):
        """
        生成API请求签名（核心：TOP签名机制）
        :param params: 待签名的请求参数字典
        :return: 生成的签名字符串
        """
        # 步骤1：按参数名ASCII码升序排序
        sorted_params = sorted(params.items(), key=lambda x: x[0])
        
        # 步骤2：拼接成"key=value&key=value"格式的字符串
        sign_str = ""
        for key, value in sorted_params:
            # 注意：参数值需要进行URL编码（符合阿里API要求）
            sign_str += f"{key}={urllib.parse.quote(str(value), safe='')}&"
        
        # 步骤3：移除末尾的&，并拼接App Secret（前后都要拼接）
        sign_str = self.app_secret + sign_str[:-1] + self.app_secret
        
        # 步骤4：HMAC-SHA1加密，再Base64编码，得到最终签名
        hmac_obj = hmac.new(self.app_secret.encode("utf-8"), sign_str.encode("utf-8"), hashlib.sha1)
        sign = base64.b64encode(hmac_obj.digest()).decode("utf-8")
        
        return sign
    
    def get_item_detail(self, item_id, fields="item_id,title,price,desc,pic_url", session=None):
        """
        查询1688商品详情
        :param item_id: 1688商品ID（必填，可从商品链接中提取）
        :param fields: 需要返回的商品字段，多个字段用逗号分隔（参考官方文档）
        :param session: 用户会话（部分接口需要，公开商品可传None）
        :return: 商品详情字典（解析后的JSON响应）
        """
        # 步骤1：构造请求参数（公共参数+业务参数）
        params = {
            # 公共参数（必须包含，阿里API固定要求）
            "app_key": self.app_key,
            "method": "alibaba.item.get",  # 接口方法名
            "format": "json",  # 响应格式（json/xml）
            "v": "2.0",  # 接口版本
            "timestamp": time.strftime("%Y-%m-%d %H:%M:%S", time.localtime()),  # 当前时间戳（格式固定）
            "sign_method": "hmac",  # 签名方法（hmac/hmac-sha256）
            # 业务参数（商品详情接口必填）
            "item_id": item_id,
            "fields": fields
        }
        
        # 可选参数：用户会话（部分接口需要登录权限）
        if session:
            params["session"] = session
        
        # 步骤2：生成签名并添加到参数中
        params["sign"] = self._generate_sign(params)
        
        # 步骤3：发送GET请求（1688商品详情接口支持GET）
        try:
            response = requests.get(self.item_detail_url, params=params, timeout=30)
            response.raise_for_status()  # 抛出HTTP请求异常（如404、500等）
        except requests.exceptions.RequestException as e:
            return {"error": "HTTP请求失败", "msg": str(e)}
        
        # 步骤4：解析JSON响应并返回
        try:
            result = response.json()
        except ValueError as e:
            return {"error": "响应解析失败", "msg": str(e)}
        
        return result

# ---------------------- 实战调用 ----------------------
if __name__ == "__main__":
    # 替换为你自己的App Key和App Secret（从阿里开放平台获取）
    MY_APP_KEY = "your_1688_app_key"
    MY_APP_SECRET = "your_1688_app_secret"
    
    # 初始化1688 API客户端
    ali_1688 = Ali1688API(MY_APP_KEY, MY_APP_SECRET)
    
    # 待查询的商品ID（示例：可从1688商品链接中提取，如https://detail.1688.com/offer/xxxxxx.html，xxxxxx就是item_id）
    target_item_id = "1234567890"
    
    # 调用商品详情查询接口
    item_detail = ali_1688.get_item_detail(target_item_id)
    
    # 打印结果
    print("=" * 50)
    print("商品详情查询结果：")
    print("=" * 50)
    import pprint
    pprint.pprint(item_detail)

四、代码详细解析

1. 类封装说明

创建 Ali1688API 类是为了更好地复用代码，将密钥、网关地址、签名逻辑封装在一起，后续扩展其他接口（如商品列表、订单查询）时更方便。

2. 核心方法：_generate_sign（签名生成）

这是调用 1688 API 的关键，一步都不能错，否则会返回「签名验证失败」：

• 排序：按参数名 ASCII 码升序，阿里 API 强制要求，保证签名的一致性。
• URL 编码：参数值可能包含特殊字符（如空格、&），需要用 urllib.parse.quote 编码，safe='' 表示不保留任何特殊字符。
• 签名拼接：前后都要拼接 App Secret，这是阿里 TOP 签名的特有规则，和其他平台的签名机制不同。
• 加密与编码：HMAC-SHA1 加密后，必须进行 Base64 编码才能得到有效的签名字符串。

3. 业务方法：get_item_detail（商品详情查询）

• 公共参数：app_key、method、format 等是阿里开放平台所有接口的通用参数，必须完整传递。
• 业务参数：item_id（商品 ID）是必填项，fields 用于指定返回的商品字段，减少无用数据传输。
• 异常处理：捕获 requests 请求异常和 JSON 解析异常，避免程序直接崩溃，同时返回清晰的错误信息。
• 响应解析：使用 response.json() 直接将 JSON 格式的响应转换为 Python 字典，方便后续处理。

4. 实战调用部分

• 替换 MY_APP_KEY 和 MY_APP_SECRET 为你自己的凭证，否则无法正常调用。
• target_item_id 需替换为真实有效的 1688 商品 ID，可从商品详情页链接中提取。
• 使用 pprint 模块打印结果，格式更清晰，方便查看。

五、常见问题与注意事项

1. 签名验证失败 ：这是最常见的问题，排查方向：
   • 检查 App Key 和 App Secret 是否正确，是否与应用对应。
   • 检查时间戳格式是否正确（必须是 %Y-%m-%d %H:%M:%S），服务器时间是否与本地时间同步（误差不能超过 10 分钟）。
   • 检查参数排序是否正确，是否遗漏公共参数。
   • 检查 App Secret 拼接是否在参数字符串的前后。
2. 权限不足：返回「接口未授权」，需在阿里开放平台应用中申请对应 API 的权限，审核通过后才能调用。
3. 商品 ID 无效 ：确保 item_id 是 1688 的有效商品 ID，且商品未下架、未私密。
4. 接口限流：阿里 API 有调用频率限制，避免短时间内大量重复调用，否则会被封禁 IP。
5. 合规性：调用 1688 API 获取的商品数据，仅可用于自身业务合规场景，不可用于爬取、倒卖、侵权等违规行为，否则会承担法律责任。

六、响应结果处理示例

如果调用成功，会返回包含商品信息的 JSON 数据，你可以提取需要的字段（如标题、价格、图片链接）：

python

运行

# 从返回结果中提取核心商品信息
if "error" not in item_detail:
    try:
        item_info = item_detail["alibaba_item_get_response"]["item"]
        print(f"\n商品标题：{item_info['title']}")
        print(f"商品价格：{item_info['price']}")
        print(f"商品图片：{item_info['pic_url']}")
    except KeyError as e:
        print(f"提取商品信息失败，缺失字段：{str(e)}")

总结

1. 调用 1688 API 的前置条件是获取阿里开放平台的App Key、App Secret及对应接口权限。
2. 核心难点是 TOP 签名机制，需严格按照「排序→拼接→加密→Base64 编码」步骤实现。
3. 代码采用类封装提高复用性，异常处理保证程序稳定性，调用时需替换真实凭证和有效商品 ID。