Productai

商品搜索服务

商品集

数据集中每一笔数据是一款商品的所有信息,如:商品名称,商品描述,价格,类别,多张图片。每一个商品集创建时,会分配到一个唯一的ID,称为PRODUCT_SET_ID

创建商品集

Python

PHP

Java

cURL

from productai import Client

cli = Client(ACCESS_KEY_ID, SECRET_KEY)
api = cli.get_product_set_api()
resp = api.create_product_set(name=SET_NAME, description=SET_DESC)
use  ProductAI\Api;

$product_ai = new ProductAI\Api\ProductSetApi($access_key_id=ACCESS_KEY_ID, $secret_key=SECRET_KEY);
$result = $product_ai->createProductSet($name=SET_NAME, ['description'=>'SET_DESC']);
$product_set_id = $result['id'];
import cn.productai.api.core.*;
import cn.productai.api.core.enums.*;
import cn.productai.api.pai.entity.productset.*;

// 设置API调用初始化参数
IProfile profile = new DefaultProfile();
profile.setAccessKeyId(ACCESS_KEY_ID);
profile.setSecretKey(SECRET_KEY);
profile.setVersion("1");
profile.setGlobalLanguage(LanguageType.Chinese);

// 设置商品集名称和描述参数
IWebClient client = new DefaultProductAIClient(profile);
CreateProductSetRequest request = new CreateProductSetRequest(SET_NAME, SET_DESC);

// 调用API,获取调用结果
CreateProductSetResponse response = client.getResponse(request);
// 获取商品集ID
String prod_set_id = response.getId();
// 获取返回的所有数据
//String json = response.getResponseJsonString();
curl -X POST \
-H 'x-ca-version: 1.0' \
-H 'x-ca-accesskeyid: ACCESS_KEY_ID' \
-H 'Content-Type: application/json' \
-d '{"name": "NAME", "description": "DESCRIPTION"}' \
https://api.productai.cn/product_sets/_0000178

输入参数

参数名称类型说明必选限制
name字符串商品集名称最多16个unicode字符,超长的部分会被自动截断
description字符串商品集的描述信息最多128个unicode字符,超长的部分会被自动截断

输出结果

200 HTTP状态码
{
"created_at" : "2018-03-26T06:30:49Z",
"creator_id" : ...,
"description" : "ProductDESC",
"id" : "y70vjzt6",
"image_set_id" : "fvh589ei",
"modified_at" : "2018-03-26T06:30:49Z",
"n_image_downloaded": 1999,
"n_image_failed": 2,
"n_image_items": 2001,
"n_items": 2002,
"name" : "ProductNAME",
"request_id" : "42fdb742-3187-11e8-96f1-024a21e9e3e6",
"status" : "not-downloaded"
}
结果字段类型说明
created_at字符串创建UTC时间,精确到秒,格式为:年-月-日T小时:分钟:秒Z
creator_id整数创建者ID
description字符串商品集的描述信息
id字符串商品集唯一ID,后续操作都需要使用此ID完成
image_set_id字符串商品集绑定的图片集唯一ID
modified_at字符串最后修改UTC时间,精确到秒,格式为:年-月-日T小时:分钟:秒Z
n_image_downloaded整数商品图片下载数
n_image_failed整数商品图片下载失败数量
n_image_items整数商品图片总数
name字符串商品集名称
request_id字符串本次调用的唯一ID,可以用于和ProductAI团队进行联调分析
status字符串目前商品集状态
非200 HTTP状态码
{
"error_code": 5001,
"message": "lineno 1 : `` should be a valid image URL less than or equal to 512 characters in length",
"request_id": "810c0180-e00e-11e7-9a0f-b217471bc47d"
}
结果字段类型说明
error_code整数表明细分错误代码
message字符串详细错误信息
request_id字符串本次调用的唯一ID,可以用于和ProductAI团队进行联调分析

错误信息

SDK/API使用http状态码来通知客户端本次调用成功和失败

http状态码error_code说明
200N/a商品集创建成功
4001007没有填写商品集名称

获取所有商品集信息

Python

PHP

Java

cURL

from productai import Client

cli = Client(ACCESS_KEY_ID, SECRET_KEY)
api = cli.get_product_set_api()
resp = api.get_product_sets()
use  ProductAI\Api;

$product_ai = new ProductAI\Api\ProductSetApi($access_key_id=ACCESS_KEY_ID, $secret_key=SECRET_KEY);
$result = $product_ai->listProductSets();
import cn.productai.api.core.*;
import cn.productai.api.core.enums.*;
import cn.productai.api.pai.entity.productset.*;

// 设置API调用初始化参数
IProfile profile = new DefaultProfile();
profile.setAccessKeyId(ACCESS_KEY_ID);
profile.setSecretKey(SECRET_KEY);
profile.setVersion("1");
profile.setGlobalLanguage(LanguageType.Chinese);

// 创建获取所有数据集request
IWebClient client = new DefaultProductAIClient(profile);
GetAllProductSetsRequest request = new GetAllProductSetsRequest();

// 调用API,获取调用结果
GetAllProductSetsResponse response = client.getResponse(request);
String json = response.getResponseJsonString();
curl -X GET \
-H 'x-ca-version: 1.0' \
-H 'x-ca-accesskeyid: ACCESS_KEY_ID' \
https://api.productai.cn/product_sets/_0000178

输入参数

N/a

输出结果

200 HTTP状态码
{
"request_id": "a05da544-0f9c-11e8-8f9b-0242ac120103",
"results": [
{
"created_at" : "2018-03-27T03:51:57Z",
"creator_id" : ...,
"description" : "This is my product set of fashion images.",
"id" : "28m1h3v9",
"image_set_id" : "b9r44tn5",
"modified_at" : "2018-03-27T03:51:57Z",
"n_image_downloaded": 1999,
"n_image_failed": 2,
"n_image_items": 2001,
"n_items": 2002,
"name" : "My Product Set",
"status" : "not-downloaded"
},
...
]
}
结果字段类型说明
results数组客户当前存在的商品集列表,单个数组元素的字段同创建商品集输出结果
request_id字符串本次调用的唯一ID,可以用于和ProductAI团队进行联调分析

错误信息

SDK/API使用http状态码来通知客户端本次调用成功和失败

http状态码error_code说明
200N/a商品集信息获取成功

获取单个商品集信息

Python

PHP

Java

cURL

from productai import Client

cli = Client(ACCESS_KEY_ID, SECRET_KEY)
api = cli.get_product_set_api(product_set_id=PRODUCT_SET_ID)
resp = api.get_product_set()
use  ProductAI\Api;

$product_ai = new ProductAI\Api\ProductSetApi($access_key_id=ACCESS_KEY_ID, $secret_key=SECRET_KEY);
$result = $product_ai->getProductSet($productSetID=PRODUCT_SET_ID);
import cn.productai.api.core.*;
import cn.productai.api.core.enums.*;
import cn.productai.api.pai.entity.productset.*;

// 设置API调用初始化参数
IProfile profile = new DefaultProfile();
profile.setAccessKeyId(ACCESS_KEY_ID);
profile.setSecretKey(SECRET_KEY);
profile.setVersion("1");
profile.setGlobalLanguage(LanguageType.Chinese);

// 创建获取数据集的request
IWebClient client = new DefaultProductAIClient(profile);
GetProductSetRequest request = new GetProductSetRequest(PRODUCT_SET_ID);

// 调用API,获取调用结果
GetProductSetResponse response = client.getResponse(request);
String json = response.getResponseJsonString();
curl -X GET \
-H 'x-ca-version: 1.0' \
-H 'x-ca-accesskeyid: ACCESS_KEY_ID' \
https://api.productai.cn/product_sets/_0000178/PRODUCT_SET_ID

输入参数

N/a

输出结果

创建商品集输出结果

错误信息

SDK/API使用http状态码来通知客户端本次调用成功和失败

http状态码error_code说明
200N/a商品集信息获取成功
4031005试图获取一个不属于自己的商品集信息
4041004商品集不存在

修改商品集名称和描述

Python

PHP

Java

cURL

from productai import Client

cli = Client(ACCESS_KEY_ID, SECRET_KEY)
api = cli.get_product_set_api(product_set_id=PRODUCT_SET_ID)
resp = api.update_product_set(name=NEW_NAME, description=NEW_DESC)
use  ProductAI\Api;

$product_ai = new ProductAI\Api\ProductSetApi($access_key_id=ACCESS_KEY_ID, $secret_key=SECRET_KEY);
$result = $product_ai->updateProductSet($productSetID=PRODUCT_SET_ID, ['name'=>'NEW_NAME', 'description'=>'NEW_DESC']);
import cn.productai.api.core.*;
import cn.productai.api.core.enums.*;
import cn.productai.api.pai.entity.productset.*;

IProfile profile = new DefaultProfile();
profile.setAccessKeyId(ACCESS_KEY_ID);
profile.setSecretKey(SECRET_KEY);
profile.setVersion("1");
profile.setGlobalLanguage(LanguageType.Chinese);

IWebClient client = new DefaultProductAIClient(profile);
UpdateProductSetRequest request = new UpdateProductSetRequest(PRODUCT_SET_ID, NEW_NAME, NEW_DESC);
request.setLanguage(LanguageType.Chinese);

UpdateProductSetResponse response = client.getResponse(request);
String json = response.getResponseJsonString();
curl -X POST \
-H 'x-ca-version: 1.0' \
-H 'x-ca-accesskeyid: ACCESS_KEY_ID' \
-H 'Content-Type: application/json' \
-d '{"name": "NEW_NAME", "description": "NEW_DESC"}' \
https://api.productai.cn/product_sets/_0000178/PRODUCT_SET_ID

输入参数

创建商品集输入参数

输出结果

创建商品集输出结果

错误信息

SDK/API使用http状态码来通知客户端本次调用成功和失败

http状态码error_code说明
200N/a商品集修改成功
4001007不能使用空字符串做为商品集名称
4031005试图获取一个不属于自己的商品集信息
4041004商品集不存在

删除商品集

Python

PHP

Java

cURL

from productai import Client

cli = Client(ACCESS_KEY_ID, SECRET_KEY)
api = cli.get_product_set_api(product_set_id=PRODUCT_SET_ID)
resp = api.delete_product_set()
use  ProductAI\Api;

$product_ai = new ProductAI\Api\ProductSetApi($access_key_id=ACCESS_KEY_ID, $secret_key=SECRET_KEY);
$result = $product_ai->deleteProductSet($productSetID=PRODUCT_SET_ID);
import cn.productai.api.core.*;
import cn.productai.api.core.enums.*;
import cn.productai.api.pai.entity.productset.*;

IProfile profile = new DefaultProfile();
profile.setAccessKeyId(ACCESS_KEY_ID);
profile.setSecretKey(SECRET_KEY);
profile.setVersion("1");
profile.setGlobalLanguage(LanguageType.Chinese);

IWebClient client = new DefaultProductAIClient(profile);
DeleteProductSetRequest request = new DeleteProductSetRequest(PRODUCT_SET_ID);
request.setLanguage(LanguageType.Chinese);

DeleteProductSetResponse response = client.getResponse(request);
curl -X DELETE \
-H 'x-ca-accesskeyid:ACCESS_KEY_ID' \
https://api.productai.cn/product_sets/_0000178/PRODUCT_SET_ID

输入参数

N/a

输出结果

N/a

错误信息

SDK/API使用http状态码来通知客户端本次调用成功和失败

http状态码error_code说明
204N/a商品集删除成功
4031005试图删除一个不属于自己的商品集
5002002删除商品集失败
4041004商品集不存在

商品管理

向商品集上传单个商品数据

Python

PHP

Java

cURL

from productai import Client

cli = Client(ACCESS_KEY_ID, SECRET_KEY)
api = cli.get_product_set_api(product_set_id=PRODUCT_SET_ID)
resp = api.add_product(
product_id='_001',
price=10000.0,
keywords='北欧风黑色布艺沙发',
image_url='http://xxxx.jpg',
meta='http://www.productai.com',
tags='sofa|black')
use  ProductAI\Api;

$product_ai = new ProductAI\Api\ProductSetApi($access_key_id=ACCESS_KEY_ID, $secret_key=SECRET_KEY);
$result = $product_ai->addProductToProductSet($productSetID=PRODUCT_SET_ID, $productID='_001', $imageUrl='http://xxxx.jpg', $args=[
'price'=>10000.0,
'keywords'=>'北欧风黑色布艺沙发',
'tags'=>'sofa|black',
'meta'=>'http://www.productai.com']);
import cn.productai.api.core.*;
import cn.productai.api.core.enums.*;
import cn.productai.api.pai.entity.productset.*;

IProfile profile = new DefaultProfile();
profile.setAccessKeyId(ACCESS_KEY_ID);
profile.setSecretKey(SECRET_KEY);
profile.setVersion("1");
profile.setGlobalLanguage(LanguageType.Chinese);

IWebClient client = new DefaultProductAIClient(profile);

String productId = "_001";
String price = "2000";
String keywords = "北欧风黑色布艺沙发";
String imageUrl = "http://yyyy.jpg";
String meta = "http://www.productai.com";
String tags = "sofa|black";

AddProductRequest request = new AddProductRequest(
PRODUCT_SET_ID, productId, price, keywords, imageUrl, meta, tags);
String json = client.getResponse(request).getResponseJsonString();
curl -X POST \
-H 'x-ca-version: 1.0' \
-H 'x-ca-accesskeyid: ACCESS_KEY_ID' \
-H 'Content-Type: application/json' \
-d '{"image_url":"https://xxxx.jpg","meta":"metadata","tags":"cartoon|square","keywords":"北欧风黑色布艺沙发","price":"2000","product_id":"_001"}' \
https://api.productai.cn/product_sets/_0000178/PRODUCT_SET_ID/products

输入参数

参数名称类型说明必选限制
productId字符串商品ID标识商品的唯一ID
price字符串商品价格商品价格,参考min_price和max_price使用
keywords字符串关键词与商品有关的关键词,索引会对该字段进行分词处理,参考keywords使用
url字符串上传图片URL最多512个unicode字符,超长会导致报错
meta字符串图片的描述信息最多512个unicode字符,超长会导致报错
tags字符串图片的标签信息会和图片数据一起进行索引。用于用户主动发起的图片加标签过滤的请求。字符串中允许包含多个标签,标签之间以"|"作为分隔,例:上衣|短袖|POLO衫。若此参数含有非ASCII字符集内的内容,请使用UTF-8编码。

输出结果

创建商品集输出结果

错误信息

SDK/API使用http状态码来通知客户端本次调用成功和失败

http状态码error_code说明
200N/a数据上传成功
4041004商品集不存在

向商品集批量上传或更新商品数据

该方法使用Upsert逻辑。如果商品ID已经存在于数据库,则不会新增记录,只会更新该商品的各个属性。上传文件格式为每行一条json格式的文本,请参见批量更改商品集数据文件示例。json中需包含:

参数名称类型说明必选限制
product_id字符串商品ID标识商品的唯一ID
price字符串商品价格商品价格,参考min_price和max_price使用
keywords字符串关键词与商品有关的关键词,索引会对该字段进行分词处理,参考keywords使用
url字符串上传图片URL最多512个unicode字符,超长会导致报错
meta字符串图片的描述信息最多512个unicode字符,超长会导致报错
tags字符串图片的标签信息会和图片数据一起进行索引。用于用户主动发起的图片加标签过滤的请求。字符串中允许包含多个标签,标签之间以"|"作为分隔,例:上衣|短袖|POLO衫。若此参数含有非ASCII字符集内的内容,请使用UTF-8编码。

Python

PHP

Java

cURL

from productai import Client

cli = Client(ACCESS_KEY_ID, SECRET_KEY)
api = cli.get_product_set_api(product_set_id=PRODUCT_SET_ID)
with open('./batch_modify_products.json') as f:
resp = api.add_products_in_bulk(f)
use ProductAI\Api;

$product_ai = new ProductAI\Api\ProductSetApi($access_key_id=ACCESS_KEY_ID, $secret_key=SECRET_KEY);
$result = $product_ai->addProductsToProductSet($productSetID=PRODUCT_SET_ID, $products='./batch_modify_products.json');
import cn.productai.api.core.*;
import cn.productai.api.core.enums.*;
import cn.productai.api.pai.entity.productset.*;

IProfile profile = new DefaultProfile();
profile.setAccessKeyId(ACCESS_KEY_ID);
profile.setSecretKey(SECRET_KEY);
profile.setVersion("1");
profile.setGlobalLanguage(LanguageType.Chinese);

IWebClient client = new DefaultProductAIClient(profile);

AddProductsBatchRequest request = new AddProductsBatchRequest(PRODUCT_SET_ID);
request.setCsvFile(new File("./batch_modify_products.json"));
request.setLanguage(LanguageType.Chinese);

AddProductsBatchResponse response = client.getResponse(request);
String json = response.getResponseJsonString()
curl -X POST \
-H 'x-ca-version: 1.0' \
-H 'x-ca-accesskeyid: ACCESS_KEY_ID' \
-F "products_to_add=@./batch_modify_products.json" \
https://api.productai.cn/product_sets/_0000178/PRODUCT_SET_ID/products

输入参数

参数名称类型说明必选限制
products_to_add文本文件文本文件内容请参看批量更改商品集数据文件示例小于50MB

输出结果

创建商品集输出结果

错误信息

向商品集上传单个商品数据错误信息说明

从商品集批量删除商品数据

Python

PHP

Java

cURL

from productai import Client

cli = Client(ACCESS_KEY_ID, SECRET_KEY)
api = cli.get_product_set_api(product_set_id=PRODUCT_SET_ID)
with open('./batch_modify_products.json') as f:
resp = api.delete_products_in_bulk(f)
use ProductAI\Api;

$product_ai = new ProductAI\Api\ProductSetApi($access_key_id=ACCESS_KEY_ID, $secret_key=SECRET_KEY);
$result = $product_ai->deleteProductsFromProductSet($productSetID=PRODUCT_SET_ID, $products='./batch_modify_products.json');
import cn.productai.api.core.*;
import cn.productai.api.core.enums.*;
import cn.productai.api.pai.entity.productset.*;

IProfile profile = new DefaultProfile();
profile.setAccessKeyId(ACCESS_KEY_ID);
profile.setSecretKey(SECRET_KEY);
profile.setVersion("1");
profile.setGlobalLanguage(LanguageType.Chinese);

IWebClient client = new DefaultProductAIClient(profile);

DeleteProductsRequest request = new DeleteProductsRequest(PRODUCT_SET_ID);
request.setCsvFile(new File("./batch_modify_products.json"));
request.setLanguage(LanguageType.Chinese);

DeleteProductsResponse response = client.getResponse(request);
String json = response.getResponseJsonString()
curl -X POST \
-H 'x-ca-version: 1.0' \
-H 'x-ca-accesskeyid: ACCESS_KEY_ID' \
-F "products_to_delete=@./batch_modify_products.json" \
https://api.productai.cn/product_sets/_0000178/PRODUCT_SET_ID/products

输入参数

参数名称类型说明必选限制
products_to_delete文本文件文本文件内容请参看批量更改商品集数据文件示例, 其中“product_id”字段标识需要删除的商品数据小于50MB

输出结果

创建商品集输出结果

错误信息

向商品集上传单个商品数据错误信息说明

使用商品ID从商品集中删除数据

Python

PHP

Java

cURL

from productai import Client

cli = Client(ACCESS_KEY_ID, SECRET_KEY)
api = cli.get_product_set_api(product_set_id=PRODUCT_SET_ID)
resp = api.delete_products(['id1', 'id2'])
use ProductAI\Api;

$product_ai = new ProductAI\Api\ProductSetApi($access_key_id=ACCESS_KEY_ID, $secret_key=SECRET_KEY);
$result = $product_ai->deleteProductsByID($productSetID=PRODUCT_SET_ID, $productIDs = ['id1', 'id2']);
import cn.productai.api.core.*;
import cn.productai.api.core.enums.*;
import cn.productai.api.pai.entity.productset.*;

IProfile profile = new DefaultProfile();
profile.setAccessKeyId(ACCESS_KEY_ID);
profile.setSecretKey(SECRET_KEY);
profile.setVersion("1");
profile.setGlobalLanguage(LanguageType.Chinese);

IWebClient client = new DefaultProductAIClient(profile);

DeleteProductsByProductSetRequest request = new DeleteProductsByProductSetRequest(PRODUCT_SET_ID, new String[]{"_001", "_002"});
request.setLanguage(LanguageType.Chinese);

DeleteProductsByProductSetResponse response = client.getResponse(request);
String json = response.getResponseJsonString();
curl -X DELETE \
-H 'x-ca-version: 1.0' \
-H 'x-ca-accesskeyid: ACCESS_KEY_ID' \
-H 'Content-Type: application/json' \
-d '{"ids":["_001","_002"]}' \
https://api.productai.cn//product_sets/_0000178/PRODUCT_SET_ID/products

输入参数

一组商品ID

输出结果

创建商品集输出结果

错误信息

向商品集上传单个商品数据错误信息说明

服务管理

创建搜索服务

Python

PHP

Java

cURL

from productai import Client

cli = Client(ACCESS_KEY_ID, SECRET_KEY)
api = cli.get_product_set_api(product_set_id=PRODUCT_SET_ID)
resp = api.create_service(name='test', scenario='material')
use ProductAI\Api;

$product_ai = new ProductAI\Api\ProductSearchServiceApi($access_key_id=ACCESS_KEY_ID, $secret_key=SECRET_KEY);
$result = $product_ai->createService($productSetID=PRODUCT_SET_ID, $name='test', $scenario='material');
import cn.productai.api.core.*;
import cn.productai.api.core.enums.*;
import cn.productai.api.pai.entity.productset.*;

IProfile profile = new DefaultProfile();
profile.setAccessKeyId(ACCESS_KEY_ID);
profile.setSecretKey(SECRET_KEY);
profile.setVersion("1");
profile.setGlobalLanguage(LanguageType.Chinese);

IWebClient client = new DefaultProductAIClient(profile);
CreateServiceRequest request = new CreateServiceRequest(PRODUCT_SET_ID, SERVICE_NAME, SCENARIO_ID);

CreateServiceResponse response = client.getResponse(request);
String json = response.getResponseJsonString()
curl -X POST \
-H 'x-ca-version: 1.0' \
-H 'x-ca-accesskeyid: ACCESS_KEY_ID' \
-H 'Content-Type: application/json' \
-d '{"name": "NAME", "scenario": "material"}' \
https://api.productai.cn/product_sets/_0000178/PRODUCT_SET_ID/services

输入参数

参数名称类型说明必选限制
name字符串服务名称必选32个字符,超过部分会被截断
scenario字符串场景类别必选必须是场景列表中定义的场景之一

输出结果

200 HTTP状态码
{
"created_at" : "2018-03-28T06:20:52Z",
"creator_id" : ...,
"id" : "n4wh8fzx",
"image_set_id" : "ftvxj8s5",
"indexed_ratio" : 0,
"last_indexed_time" : null,
"last_updated_at" : null,
"n_indexed" : 0,
"name" : "product-service",
"product_set_id": "qszy6635",
"request_id" : "29d7ed90-3250-11e8-963a-7e00c202692f",
"scenario" : "fashion_5_6",
"status" : "running",
"status_duration" : 0,
"type" : 1
}
结果字段类型说明
created_at字符串创建UTC时间,精确到秒,格式为:年-月-日T小时:分钟:秒Z
creator_id整数创建者ID
id字符串搜索服务唯一ID,后续操作都需要基于此ID进行
image_set_id字符串搜索服务基于的数据集ID
indexed_ratio浮点数索引完成率 = 索引的图片数 / 下完成的图片数
last_indexed_time字符串搜索服务最后一次索引部署时间
last_updated_at字符串最后修改UTC时间,精确到秒,格式为:年-月-日T小时:分钟:秒Z
n_indexed整数当前搜索服务线上索引量
name字符串搜索服务名称
product_set_id字符串商品集ID
request_id字符串本次调用的唯一ID,可以用于和ProductAI团队进行联调分析
scenario字符串搜索服务基于的场景,参考场景列表
status字符串目前搜索服务状态,目前只有running一种
status_duration整数N/a
type整数N/a
非200 HTTP状态码
{
"error_code": 2003,
"message": "Failed to Create Service",
"request_id": "a0393714-e331-11e7-9a0f-b217471bc47d"
}
结果字段类型说明
error_code整数表明细分错误代码
message字符串详细错误信息
request_id字符串本次调用的唯一ID,可以用于和ProductAI团队进行联调分析

错误信息

SDK/API使用http状态码来通知客户端本次调用成功和失败

http状态码error_code说明
200N/a查询成功
4002003scenario中指定的场景不存在

获取所有服务信息

Python

PHP

cURL

from productai import Client

cli = Client(ACCESS_KEY_ID, SECRET_KEY)
api = cli.get_product_search_api()
resp = api.list_services()
use ProductAI\Api;

$product_ai = new ProductAI\Api\ProductSearchServiceApi($access_key_id=ACCESS_KEY_ID, $secret_key=SECRET_KEY);
$result = $product_ai->listServices();
curl -X GET \
-H 'x-ca-version: 1.0' \
-H 'x-ca-accesskeyid: ACCESS_KEY_ID' \
https://api.productai.cn/product_sets/_0000178/services

输入参数

N/A

输出结果

Python

{
"request_id": "465b84ca-6a29-11e8-8cb4-d680a9823a64",
"services": [
{
"created_at": "2018-05-19T00:42:23Z",
"creator_id": ...,
"id": "h2pcwx8p",
"image_set_id": "0w3ftsbl",
"indexed_ratio": 1.0,
"last_indexed_time": "2018-06-03T09:31:15Z",
"last_updated_at": "2018-06-03T08:27:06Z",
"n_indexed": 100,
"name": "prd_test",
"product_set_id": "qszy6635",
"scenario": "material",
"status": "running",
"status_duration": 0,
"type": 1
}
]
}
结果字段类型说明
request_id字符串本次调用的唯一ID,可以用于和ProductAI团队进行联调分析
services数组包含所有运行中的商品服务信息,其中数组元素中字段含义,请参见创建搜索服务输出结果

获取搜索服务信息

Python

PHP

cURL

from productai import Client

cli = Client(ACCESS_KEY_ID, SECRET_KEY)
api = cli.get_product_search_api(SERVICE_ID)
resp = api.get_service()
use ProductAI\Api;

$product_ai = new ProductAI\Api\ProductSearchServiceApi($access_key_id=ACCESS_KEY_ID, $secret_key=SECRET_KEY);
$result = $product_ai->getService($serviceID=SERVICE_ID);
curl -X GET \
-H 'x-ca-version: 1.0' \
-H 'x-ca-accesskeyid: ACCESS_KEY_ID' \
https://api.productai.cn/product_sets/_0000178/services/SERVICE_ID

输入参数

N/A

输出结果

获取所有服务信息输出结果相同

错误信息

SDK/API使用http状态码来通知客户端本次调用成功和失败

http状态码说明
200获取成功
404服务不存在

更新搜索服务名称

Python

PHP

cURL

from productai import Client

cli = Client(ACCESS_KEY_ID, SECRET_KEY)
api = cli.get_product_search_api(SERVICE_ID)
resp = api.update_service(name='NEW_NAME')
use ProductAI\Api;

$product_ai = new ProductAI\Api\ProductSearchServiceApi($access_key_id=ACCESS_KEY_ID, $secret_key=SECRET_KEY);
$result = $product_ai->updateService($serviceID=SERVICE_ID, $args=["name"=>'NEW_NAME']);
curl -X PATCH \
-H 'x-ca-version: 1.0' \
-H 'x-ca-accesskeyid: ACCESS_KEY_ID' \
-H 'Content-Type: application/json' \
-d '{"name": "NEW_NAME"}' \
https://api.productai.cn/product_sets/_0000178/services/SERVICE_ID

输入参数

参数名称类型说明必选限制
name字符串新服务名称必选32个字符,超过部分会被截断

输出结果

创建搜索服务输出结果相同

错误信息

SDK/API使用http状态码来通知客户端本次调用成功和失败

http状态码说明
200更新成功
400试图设置名称为空
404服务不存在

删除搜索服务

Python

PHP

cURL

from productai import Client

cli = Client(ACCESS_KEY_ID, SECRET_KEY)
api = cli.get_product_search_api(SERVICE_ID)
resp = api.delete_service()
use ProductAI\Api;

$product_ai = new ProductAI\Api\ProductSearchServiceApi($access_key_id=ACCESS_KEY_ID, $secret_key=SECRET_KEY);
$result = $product_ai->deleteService($serviceID=SERVICE_ID);
curl -X DELETE \
-H 'x-ca-version: 1.0' \
-H 'x-ca-accesskeyid: ACCESS_KEY_ID' \
https://api.productai.cn/product_sets/_0000178/services/SERVICE_ID

输入参数

N/A

输出结果

N/A

错误信息

SDK/API使用http状态码来通知客户端本次调用成功和失败

http状态码说明
200删除成功
404服务不存在

商品搜索

Python

PHP

cURL

from productai import Client

cli = Client(ACCESS_KEY_ID, SECRET_KEY)
api = cli.get_product_search_api(SERVICE_ID)

# 用图片URL查询
resp = api.query(image='http://yyyy', loc='0.1-0.1-0.8-0.7')

# 或者直接上传本地图片查询
with open("zzzz.jpg", mode='rb') as search:
resp = api.query(
image=search,
count=2,
tags=['MALE', 'SHOES'],
keywords='hello',
min_price=100,
max_price=5000)

# 用图片URL结合tags过滤,进行查询, 指定返回结果上限,默认为20
resp = api.query(
image='http://yyyy',
count=2,
tags=['MALE', 'SHOES'],
keywords='hello',
min_price=100,
max_price=5000)
use ProductAI\Api;

$product_ai = new PProductAI\Api\ProductSearchServiceApi($access_key_id=ACCESS_KEY_ID, $secret_key=SECRET_KEY);

// 用图片URL查询
$result = $product_ai->search(
$service_id=SERVICE_ID,
$image='http://yyyy',
$options=[
"loc" => "0.5-0.1-0.1-0.5",
"count" => 10,
"tags" => "a|b",
"min_price" => 100,
"max_price" => 5000,
"keywords" => "hello"
]);

// 上传本地文件查询
$result = $product_ai->search(
$service_id=SERVICE_ID,
$image='@./zzzz.jpg',
$options=[
"loc" => "0.5-0.1-0.1-0.5",
"count" => 10,
"tags" => "a|b",
"min_price" => 100,
"max_price" => 5000,
"keywords" => "hello"
]);
# 用图片URL查询
curl -X POST \
-H 'x-ca-version: 1.0' \
-H 'x-ca-accesskeyid: ACCESS_KEY_ID' \
-H 'Content-Type: application/json' \
-d '{"url":"http://yyyy","count":"2","tags":{"and":["MALE","SHOES"]},"min_price":"100","max_price":"5000","keywords":"hello"}' \
product_search https://api.productai.cn/product_search/SERVICE_ID

# 上传本地文件查询
curl -X POST \
-H 'x-ca-version: 1.0' \
-H 'x-ca-accesskeyid: ACCESS_KEY_ID' \
-F "search=@zzzz.jpg" \
-F "count=2" \
-F 'tags={"and":["MALE","SHOES"]}' \
-F "min_price=100" \
-F "max_price=5000" \
-F "keywords=hello" \
https://api.productai.cn/product_search/SERVICE_ID

输入参数

参数名称类型说明必选限制
image字符串或者文件内容上传图片URL或者为图片本身N/a
count整数制定返回搜索结果数量默认数量20,取值范围1-3000,不能超过3000
min_price浮点数商品价格筛选下限正数,参考min_price和max_price使用
max_price浮点数商品价格筛选上限正数,并且应大于min_price,参考min_price和max_price使用
keywords字符串用于做模糊文本筛选的字段,参考keywords使用N/a
tags字符串用于做精准文本筛选的字段N/a

输出结果

{
"detect_time": "0.000",
"detection_score": null,
"download_time": "0.381",
"ds": "e8ie3j2s",
"filter_time": 0.028,
"is_err": 0,
"labels": null,
"loc": [
0,
0,
316,
470
],
"most_common_tags": [],
"preprocess_time": "0.005",
"request_id": "755a639c-634c-11e8-91b4-fa76868b7be4",
"results": [
{
"keywords": "key",
"metadata": null,
"price": 10,
"product_id": "1",
"score": 1,
"url": "https://styleai-shopping.oss-cn-beijing.aliyuncs.com/14d1b1e8a38ae767cc67834799be5ef9ed4595b9.jpg",
"url_id": 1
},
{
"keywords": "key",
"metadata": null,
"price": 10,
"product_id": "2",
"score": 1,
"url": "https://styleai-shopping.oss-cn-beijing.aliyuncs.com/14d1b1e8a38ae767cc67834799be5ef9ed4595b9.jpg",
"url_id": 1
}
],
"searchtime": "0.125",
"time": 0.706,
"type": null,
"ver": "20180529-112740"
}

results字段为一个数组,包含全部搜索结果,详解参见Results字段详解

时间相关字段说明

结果字段类型说明
detect_time字符串检测服务时间消耗,单位为秒
download_time字符串图片下载时间消耗,单位为秒
preprocess_time字符串图片搜索前,预处理时间消耗,单位为秒
searchtime字符串搜索时间消耗,单位为秒
time字符串服务器端全部时间消耗,单位为秒

检测器相关字段说明

结果字段类型说明
detect_time字符串检测服务时间消耗,单位为秒
detection_score浮点数检测服务返回的置信度
loc数组检测服务返回,图中最有可能的搜索目标物体,四个数值依次为x, y, w, h
type数组检测服务返回,图中最有可能的物体类别

其他相关字段说明

结果字段类型说明
ds字符串将废弃,请勿使用
is_err整数将废弃,请勿使用
most_common_tags数组详细使用,请参见ret_img_tags使用
request_id字符串本次请求的唯一识别ID,用于和ProductAI平台进行联调诊断
ver字符串索引版本号

Results字段详解

{
"keywords": "key",
"metadata": null,
"price": 10,
"product_id": "1",
"score": 1,
"url": "https://styleai-shopping.oss-cn-beijing.aliyuncs.com/14d1b1e8a38ae767cc67834799be5ef9ed4595b9.jpg",
"url_id": 1
}
结果字段类型说明
product_id字符串产品唯一ID
url字符串搜索结果图片对应的链接地址
price浮点数产品价格
keywords字符串产品模糊搜索内容
score浮点数与Query图片的相似度
metadata字符串为被搜索出来的图片索引时上传的metadata。详情参见metadata使用
tags数组包含被搜索图片上传时,包含的tags数据。详情参见ret_img_tags使用

错误信息

SDK/API使用http状态码来通知客户端本次调用成功和失败

http状态码说明
200搜索成功
404服务不存在

最佳实践

keywords使用

商品数据集中每个商品,索引时都接受一个关键词字段。索引会对该字段进行分词处理,搜索时通过keywords参数进行过滤,确保返回的商品包含keywords中的文本。

返回keywords属性中包含“沙发”的商品

Python

PHP

cURL

api.query(image='http://xxxx.jpg', keywords=u'沙发')
api->search($service_id=SERVICE_ID, $image='http://xxxx.jpg', $options=[ 'keywords'=>'沙发' ]);
curl -X POST \
-H 'x-ca-version: 1.0' \
-H 'x-ca-accesskeyid: ACCESS_KEY_ID' \
-H 'Content-Type: application/json' \
-d '{"url":"http://xxxx.jpg","keywords":"沙发"}' \
https://api.productai.cn/product_search/SERVICE_ID

min_price和max_price使用

商品数据集中每一个商品都可以上传一个价格信息。搜索时可以通过使用min_price和max_price参数进行过滤,确保返回价格区间内的商品。

返回价格在1000.0到50000.0之间的结果。

Python

PHP

cURL

api.query(image='http://xxxx.jpg', min_price=1000.0, max_price=50000.0)
api->search($service_id=SERVICE_ID, $image='http://xxxx.jpg', $options=[ 'max_price'=>50000.0, 'min_price'=>1000.0]);
curl -X POST \
-H 'x-ca-version: 1.0' \
-H 'x-ca-accesskeyid: ACCESS_KEY_ID' \
-H 'Content-Type: application/json' \
-d '{"url":"http://xxxx.jpg","min_price":"1000","max_price":"50000"}' \
https://api.productai.cn/product_search/SERVICE_ID

返回价格在1000.0以上的结果。

Python

PHP

cURL

api.query(image='http://xxxx.jpg', min_price=1000.0)
api->search($service_id=SERVICE_ID, $image='http://xxxx.jpg', $options=[ 'min_price'=>1000.0]);
curl -X POST \
-H 'x-ca-version: 1.0' \
-H 'x-ca-accesskeyid: ACCESS_KEY_ID' \
-H 'Content-Type: application/json' \
-d '{"url":"http://xxxx.jpg","min_price":"1000"}' \
https://api.productai.cn/product_search/SERVICE_ID

返回价格在50000.0以下的结果。

Python

PHP

cURL

api.query(image='http://xxxx.jpg', max_price=50000.0)
api->search($service_id=SERVICE_ID, $image='http://xxxx.jpg', $options=[ 'max_price'=>50000.0]);
curl -X POST \
-H 'x-ca-version: 1.0' \
-H 'x-ca-accesskeyid: ACCESS_KEY_ID' \
-H 'Content-Type: application/json' \
-d '{"url":"http://xxxx.jpg","max_price":"50000"}' \
https://api.productai.cn/product_search/SERVICE_ID