腾讯云APE-SDK接入文档

概述：

此文档适用于腾讯云正版图库直通车的合作客户，将SDK接入自己的平台后，客户可以更方便的使用腾讯云正版图库提供的各种能力。

接入前提：

您已注册腾讯云账号，完成实名认证，并成为腾讯云图库会员。

文档目录：

一、引入SDK并初始化实例

通过npm安装ape-js-sdk。

npm i ape-js-sdk

在您的web页面引入sdk，并实例化对象，代码示例如下:

import ApeSdk from 'ape-js-sdk'

const sdk = new ApeSdk({
	sign: 'XXXXX’
})

参数说明：

字段名	类型	是否必填	描述
sign	string	是	用户签名，由开发者后端提供

二、后端鉴权生成签名

签名授权交互如下：

授权流程：

开发者浏览器端向开发者服务端发起请求，申请浏览器端访问签名;
开发者服务端在对请求来源及内容做适当鉴权之后，根据签名算法，生成对应操作的访问签名，并返回给浏览器端;
开发者浏览器端将访问签名传递给图库直通车 APE-SDK;
图库直通车APE-SDK 会携带签名执行相关操作，图库直通车服务端在进行签名合法性校验，以及用户操作权限校验之后，会执行相应操作。

签名生成步骤：

获取云API密钥：
- 登录腾讯云控制台，选择云产品 > 访问管理 > API密钥管理；
- 获取云API密钥，如果没有可以新建，获取一对SecretId和SecretKey备用。
拼接明文串:

按照 URL QueryString 的格式要求拼接签名明文串 original，其格式如下：

secretId=[secretId]&currentTimeStamp=[currentTimeStamp]&expireTime=[expireTime]&random=[random]&channelId=[channelId]&imageDownloadMaxNum=[imageDownloadMaxNum]

上述 original 中的[secretId]、[currentTimeStamp]、[expireTime]、[random]、[channelId]及[imageDownloadMaxNum]需要自行替换成具体的参数值。

original 除了可以包含必选参数，还可包含任意多个选填参数，详细请参见签名参数。
参数值必须经过 UrlEncode，否则可能导致 QueryString 解析失败。

将明文串转为最终签名。

下面以 Java 语言作为示例进行实现，其他语言的实现请参见签名示例。

用已获取的 SecretKey 对明文串 original 进行 HMAC-SHA1 加密，得到 signatureTmp：

SecretKeySpec secretKey = new SecretKeySpec(this.secretKey.getBytes("UTF-8"), mac.getAlgorithm());
mac.init(secretKey);
byte[] signatureTmp = mac.doFinal(original.getBytes("UTF-8"));

将明文串 original 使用 UTF-8 编码成字节数组，然后把 signatureTmp 与该数组进行合并，最后把合并后的结果进行 Base64 编码，得到最终签名 signature：

String signature = base64Encode(byteMerger(signatureTmp, original.getBytes("utf8")));

签名参数说明:

参数名称	必选	类型	说明
secretId	是	String	云 API 密钥中的 SecretId。
currentTimeStamp	是	Integer	当前 Unix 时间戳。
expireTime	是	Integer	签名到期 Unix 时间戳，当currentTimeStamp>expireTime时，签名会失效。`expireTime = currentTimeStamp + 签名有效时长`。
random	是	Integer	随机数，类型为32位无符号整型。
channelId	是	String	频道ID，
imageDownloadMaxNum	是	Integer	图片下载最大数量，当同一签名下载图片次数超过此限制，签名将失效。

三．查询频道详细信息

此方法用于获取频道的详细信息，包括图片分类名称等，代码示例如下：

sdk.DescribeChannel().then((res)=>{

});

参数说明：

类别	字段名	类型	是否必填	描述
response	CategoryNames	Array of String		分类名称
	ChannelName	String		频道名称

四．搜索图片

此方法用于根据各种条件搜索图片结果，代码示例如下：

sdk.SearchImage({
    Keyword: 'XXX',
    Orientation: Orientation.ALL,
    ImageSenseType: SenseType.ALL,
    Category: '',
    Offset: 0,
    Limit: 20,
}).then((res)=>{

});

参数说明：

类别	字段名	类型	是否必填	描述
request	Offset	Number	否	页码，默认0
	Limit	Number	否	页长，默认100
	Keyword	String	否	关键词，可以为空字符串
	Orientation	String	否	构图方式: Orientation.ALL (全部)Orientation.HORIZONTAL (横图)Orientation.VERTICAL (竖图)Orientation.SQUARE (方图)
	ImageSenseType	String	否	图片类型: SenseType.ALL (全部)SenseType.PHOTO (照片)SenseType.ILLUSTRATION (插画)SenseType.TEMPLATE (模板)
	Category	String	否	分类名称，例如：建筑、背景、季节等
response	Total	Number		搜索结果总数
	Items	Array of ImageItem		图片素材列表

ImageItem

字段名	类型	描述
ImageId	String	图片Id
Title	String	图片标题
PreviewUrl	String	预览图链接
Height	Number	图高
Width	Number	图宽

五．引用素材（获取图片原图链接）

此方法用于获取图片源地址，代码示例如下：

sdk.DownloadImage({
   ImageId: 'ape-xkdiq1',
}).then((res)=>{

});

参数说明：

类别	字段名	类型	是否必填	描述
request	ImageId	String	是	图片Id
response	ImageUrl	String		源图url

注意：源图url 有效期 30 分钟，请勿直接将该 URL 持久存储，如有必要请将图片内容转存到自己的图片存储服务。

六．各编程语言生成签名示例

Java 签名示例

import sun.misc.BASE64Encoder;
import javax.crypto.Mac;
import javax.crypto.spec.SecretKeySpec;
import java.net.URLEncoder;
import java.util.HashMap;
import java.util.Map;
import java.util.Random;

public class ApeSign {
    public static void main(String[] args) throws Exception {
        Long currentTime = System.currentTimeMillis() / 1000;
        Integer random = new Random().nextInt(java.lang.Integer.MAX_VALUE);
        Long expireTime = currentTime + 5 * 60; // 5分钟有效
        Integer imageDownloadMaxNum = 20; // 签名可下载图片最大次数

        HashMap<String, String> paramMap = new HashMap<String, String>();
        // 必填参数
        paramMap.put("secretId", "Your SecretId");
        paramMap.put("currentTimeStamp", currentTime.toString());
        paramMap.put("random", random.toString());
        paramMap.put("expireTime", expireTime.toString());
        paramMap.put("channelId", "Your channelId");
        paramMap.put("imageDownloadMaxNum", imageDownloadMaxNum);
        

        String secretKey = "Your SecretKey";
        String original = urlEncodeUTF8(paramMap);

        Mac mac = Mac.getInstance("HmacSHA1");
        SecretKeySpec keySpec = new SecretKeySpec(secretKey.getBytes("UTF-8"), mac.getAlgorithm());
        mac.init(keySpec);
        byte[] hash = mac.doFinal(original.getBytes("UTF-8"));
        byte[] signBuffer = byteMerger(hash, original.getBytes("UTF-8"));
        String sign = new String(new BASE64Encoder().encode(signBuffer).getBytes());
        sign = sign.replace(" ", "").replace("\n", "").replace("\r", "");

        System.out.println(sign);
    }

    private static byte[] byteMerger(byte[] byte1, byte[] byte2) {
        byte[] byte3 = new byte[byte1.length + byte2.length];
        System.arraycopy(byte1, 0, byte3, 0, byte1.length);
        System.arraycopy(byte2, 0, byte3, byte1.length, byte2.length);
        return byte3;
    }

    private static String urlEncodeUTF8(Map<String, String> map) throws Exception {
        StringBuilder sb = new StringBuilder();
        for (Map.Entry<String, String> entry : map.entrySet()) {
            if (sb.length() > 0) {
                sb.append("&");
            }
            sb.append(String.format("%s=%s",
                    URLEncoder.encode(entry.getKey(), "UTF-8"),
                    URLEncoder.encode(entry.getValue(), "UTF-8")
            ));
        }
        return sb.toString();
    }
}

Go 签名示例

package main

import (
	"crypto/hmac"
	"crypto/sha1"
	"encoding/base64"
	"fmt"
	"math/rand"
	"net/url"
	"strconv"
	"time"
)

func main() {
	secretId := "Your SecretId"
	secretKey := "Your SecretKey"
    imageDownloadMaxNum := 20 // 签名可下载图片最大次数

	currentTime := time.Now().Unix()
	expireTime := currentTime + 5 * 60 // 签名有效期：5分钟
	rand.Seed(time.Now().Unix())
	random := rand.Uint32()

	values := url.Values{}
	values.Add("secretId", secretId)
	values.Add("currentTimeStamp", strconv.FormatInt(currentTime, 10))
	values.Add("expireTime", strconv.FormatInt(expireTime, 10))
	values.Add("random", strconv.Itoa(int(random)))
    values.Add("channelId", "Your channelId");
	values.Add("imageDownloadMaxNum", imageDownloadMaxNum);

	queryStr := values.Encode()
	mac := hmac.New(sha1.New, []byte(secretKey))
	mac.Write([]byte(queryStr))
	macBuffer := mac.Sum(nil)

	origin := string(macBuffer) + queryStr
	signature := base64.StdEncoding.EncodeToString([]byte(origin))
	fmt.Println(signature)
}

Python 签名示例

#!/usr/local/bin/python3
#coding=utf-8

import time
import random
import hmac
import hashlib
import base64
from urllib.parse import urlencode

# 确定签名的当前时间和失效时间
currentTime = int(time.time())
expireTime = currentTime + 5 * 60  # 签名有效期：5分钟
imageDownloadMaxNum = 20 # 签名可下载图片最大次数

# 参数
argList = {
    "secretId" : "Your SecretId",
    "currentTimeStamp" : currentTime,
    "expireTime" : expireTime,
    "random" : random.randint(0, 999999),
    "channelId": "Your channelId",
    "imageDownloadMaxNum": imageDownloadMaxNum
}

secretKey = "Your SecretKey"

# 计算签名
original = urlencode(argList)
secretKeyHmac = hmac.new(bytes(secretKey, 'utf-8'), bytes(original, 'utf-8'), hashlib.sha1)
secretKeySha = secretKeyHmac.digest()
signTemp = bytes(secretKeySha) + bytes(original, 'utf-8')
sign = base64.b64encode(signTemp)

print("sign: ", sign)

PHP 签名示例

<?php
// 确定签名的当前时间和失效时间
$currentTime = time();
$expireTime = $currentTime + 5 * 60;  // 签名有效期：5分钟
$imageDownloadMaxNum = 20; // 签名可下载图片最大次数

// 必填参数
$arg_list = array(
    "secretId" => "Your SecretId",
    "currentTimeStamp" => $currentTime,
    "expireTime" => $expireTime,
    "random" => rand(),
    "channelId" => "Your channelId",
    "imageDownloadMaxNum" => imageDownloadMaxNum,
);

$secretKey = "Your SecretKey";

// 计算签名
$original = http_build_query($arg_list);
$signature = base64_encode(hash_hmac('SHA1', $original, $secretKey, true).$original);

echo $signature;

Node.js 签名示例

var querystring = require("querystring");
var crypto = require('crypto');

// 确定签名的当前时间和失效时间
var currentTime = parseInt((new Date()).getTime() / 1000);
var expireTime = currentTime + 5 * 60;  // 签名有效期：5分钟
var imageDownloadMaxNum = 20; // 签名可下载图片最大次数

// 必填参数
var arg_list = {
    secretId : "Your SecretId",
    currentTimeStamp : currentTime,
    expireTime : expireTime,
    random : Math.round(Math.random() * Math.pow(2, 32)),
    channelId: "Your channelId", 
    imageDownloadMaxNum: imageDownloadMaxNum,
};

var secretKey = "Your SecretKey";

// 计算签名
var orignal = querystring.stringify(arg_list);
var orignal_buffer = Buffer.from(orignal, "utf8");
var hmac = crypto.createHmac("sha1", secretKey);
var hmac_buffer = hmac.update(orignal_buffer).digest();
var sign = Buffer.concat([hmac_buffer, orignal_buffer]).toString("base64");

console.log(sign);

ape-js-sdk

腾讯云APE-SDK接入文档

概述：

接入前提：

文档目录：

一、引入SDK并初始化实例

二、后端鉴权生成签名

签名授权交互如下：

授权流程：

签名生成步骤：

三．查询频道详细信息

四．搜索图片

五．引用素材（获取图片原图链接）

六．各编程语言生成签名示例

Readme

Keywords

Package Sidebar

Install

Weekly Downloads

Version

License

Unpacked Size

Total Files

Last publish

Collaborators

ape-js-sdk

腾讯云APE-SDK接入文档

概述：

接入前提：

文档目录：

一、引入SDK并初始化实例

二、后端鉴权生成签名

签名授权交互如下：

授权流程：

签名生成步骤：

三．查询频道详细信息

四．搜索图片

五．引用素材（获取图片原图链接）

六．各编程语言生成签名示例

Readme

Keywords

Package Sidebar

Install

DownloadsWeekly Downloads

Version

License

Unpacked Size

Total Files

Last publish

Collaborators

Weekly Downloads