商品检索服务的数据库层支持图像存储和检索,您可以通过POST方式调用该服务提供的接口,对数据库中的数据进行增加、查询、删除、检索及清理操作。本文介绍各接口的详细信息,包括POST内容示例、输入参数、输出参数及输出示例。

商品检索服务的数据库层提供的接口列表如下: 在数据库中,每张图片数据必须指定对应的group_id,从而实现后续的查询和检索功能。下文详细介绍数据库层提供的接口,此处仅介绍每个接口的特有参数,关于接口中的通用参数说明请参见接口格式及调用说明(必读)

注册数据(set)

注册数据指用户向服务内指定的数据库添加数据。该接口支持通过以下两种方式添加数据:
  • 通过文件列表添加数据。文件的每一行格式为[image_url,group_id](此处假设行内分隔符为英文逗号。在实际使用中,您可以根据需求设置行内分隔符)。
  • 通过图片文件(或文件URL),并指定group_idintra_id,添加数据。
以下介绍该接口的调用示例及参数说明:
  • POST内容示例
    • 单图像注册
      {   
          "db_name": "oss_hz", # 用户指定的数据库名称。
          "function_name": "set", # 注册数据的接口名称。
          "function_params": {
              "image_path": "xxxx", # 数据的地址。
              "group_id" : "6000" # 数据的ID信息。
              "intra_id" : 1   # 数据在group内部的ID,选填,可以自动扩展。
          },
      }
    • 图像列表注册
      {   
          "db_name": "oss_hz", # 用户指定的数据库名称。
          "function_name": "set", # 注册数据的接口名称。
          "function_params": {
              "filelist": "xxxx",  # 图像列表数据的地址。
              "delimiter" : " "    # 图像列表行内分隔符,默认使用空格(" ")。
              "image_root" : 1     # 图像root地址。
          },
      }
      说明 批量注册数据时,接口会直接返回相关提示,并在服务后台进行批量注册。您可以通过get接口查询添加进度和失败图片。
  • 输入参数说明
    参数 描述 是否必选 类型
    image_path 图片的URL,仅支持OSS地址格式。
    说明 仅开通了OSS的用户可以使用OSS地址。
    STRING
    image 图片内容的Base 64编码字符串,该参数与image_path互斥。 否(与image_path二选一) STRING
    group_id 注册单张图片必须指定的ID信息。 STRING
    intra_id 注册单张图片时,用于区分统一ID下的不同图片。 INT
    filelist 列表注册时使用的图像列表文件,文件每行的格式为[image_url,group_id](此处假设行内分隔符为英文逗号),即每行标注一张图片的URL和group_id STRING
    delimiter 列表注册时,图像列表行内的分隔符,即image_urlgroup_id之间的分隔符,默认为空格(" ")。 STRING
    image_root 列表注册时,图像源地址。 STRING
  • 输出参数说明
    参数 描述 类型
    request_id 请求的唯一标识。 STRING
    success 请求是否成功,取值包括:
    • true:请求成功。
    • false:请求失败。
    BOOL
    info 返回调用函数的相关信息。 DICT
    error_code 请求失败时,返回的错误码。 INT
    error_msg 请求失败时,返回的错误信息。 STRING
  • 输出示例
    {
        "request_id": "6bc8af06-5c9f-40b8-a725-5646fc97****", 
        "success": true, 
        "info": {"add": true}
        // "info": "Adding by file list is running in backstage, \
        //  refer schedule & failed_log by get function"
    }
    两个正斜线(//)注释掉的内容表示可能输出的内容,会根据您不同的输入而变化。

查询数据(get)

查询数据指用户向服务内指定的数据库查询指定group_idintra_id的数据,该接口支持通过以下两种方式查询数据:
  • 指定group_id进行查询,接口返回数据库内所有符合该group_id的相关信息。
  • 指定group_idintra_id进行查询,接口返回数据库内符合查询条件的唯一数据记录的相关信息。
以下介绍该接口的调用示例及参数说明:
  • POST内容示例
    {   
        "db_name": "oss_hz", # 用户指定的数据库名称。
        "function_name": "get", # 查询数据的接口名称。
        "function_params": {
            "group_id" : "6000" # 待查询的ID信息。
            "intra_id" : 1   # 待查询数据的内部ID,选填。
        },
    }
  • 输入参数说明
    参数 描述 是否必选 类型
    group_id 待查询数据的group_id STRING
    intra_id 待查询数据的intra_id,如果未指定,则系统会自动补充。 INT
    setdata_log 是否查询批量添加数据的进度,取值包括:
    • true:查询批量添加数据的进度。
    • false:无需查询批量添加数据的进度。
    BOOL
  • 输出参数说明
    参数 描述 类型
    request_id 请求的唯一标识。 STRING
    success 请求是否成功,取值包括:
    • true:请求成功。
    • false:请求失败。
    BOOL
    info 如果查询成功,则返回查询到的信息。如果查询失败,则返回相关提示。 DICT
    error_code 请求失败时,返回的错误码。 INT
    error_msg 请求失败时,返回的错误信息。 STRING
  • 输出示例
    {
        "request_id": "47b25489-3ceb-40b1-b469-54f19236****", 
        "success": true, 
        "info": {"oss_path_name": ["oss://xxxxxxx/data/test_data/bengio1.jpeg"], "group_id": ["6000"], "intra_id": [0.0]}
         // "info": {"oss_path_name": [], "group_id": [], "intra_id": []}
         // "info": {"set_data_byfilelist": true, "now_success_num": 200, "total_num": 5000, "failed_log": []}
    }
    两个正斜线(//)注释掉的内容表示没有查询到相关数据时,可能的输出内容。

删除数据(delete)

删除数据指用户向服务内指定的数据库删除指定group_idintra_id的数据,该接口支持通过以下两种方式删除数据:
  • 指定group_id进行删除,可以删除数据库内所有符合该group_id的相关信息。
  • 指定group_idintra_id进行删除,仅删除数据库内符合条件的唯一数据记录的相关信息。
以下介绍该接口的调用示例及参数说明:
  • POST内容示例
    {   
        "db_name": "oss_hz", # 用户指定的数据库名称。
        "function_name": "delete", # 删除数据的接口名称。
        "function_params": {
            "group_id" : "6000" # 待删除的ID信息。
            "intra_id" : 1   # 待删除数据的内部ID,选填。
        },
    }
  • 输入参数说明
    参数 描述 是否必选 类型
    group_id 待删除数据的group_id STRING
    intra_id 待删除数据的intra_id,如果未指定,则删除group_id对应的所有数据。 INT
  • 输出参数说明
    字段 描述 类型
    request_id 请求的唯一标识。 STRING
    success 请求是否成功,取值包括:
    • true:请求成功。
    • false:请求失败。
    BOOL
    info 是否删除成功,取值包括:
    • true:删除成功。
    • false:删除失败。如果数据不存在,则返回false
    BOOL
    error_code 请求失败时,返回的错误码。 INT
    error_msg 请求失败时,返回的错误信息。 STRING
  • 输出示例
    {
        "request_id": "e8a8c95e-d2e2-4b68-b403-2fc90bbc****", 
        "success": true, 
        "info": true
    }

检索数据(search)

检索数据指用户向服务内指定的数据库发送图片检索请求,系统会提取该图片的特征,并在已注册的数据中找到与该特征最接近的特征对应的图片,进而返回该图片的相关信息。该接口支持以下检索策略:
  • 与注册数据类似,检索数据支持输入图片的URL或Base 64编码。
  • 检索数据可以指定TOPK距离的召回。
  • 检索数据可以指定是否返回被检索到图片的原始数据地址,默认不返回。
以下介绍该接口的调用示例及参数说明:
  • POST内容示例
    {   
        "db_name": "oss_hz",
        "function_name": "search",
        "function_params": {
            "image_path" : "oss://xxxxxx/data/test_data/bengio2.jpeg",
            "topk":5,
            "return_file_path" : true,
         }   
    }
  • 输入参数说明
    字段 描述 是否必选 类型
    image_path 图片的URL,仅支持OSS地址格式。
    说明 仅开通了OSS的用户可以使用OSS地址。
    STRING
    image 图片内容的Base 64编码字符串,与image_path互斥。 否(与image_path 二选一) STRING
    topk 检索返回的记录数量。 INT
    return_file_path 是否返回原始数据地址,取值包括:
    • false:默认值,表示不返回原始数据地址。
    • true:返回原始数据地址。
    BOOL
  • 输出参数说明
    参数 描述 Type
    request_id 请求的唯一标识。 STRING
    success 请求是否成功,取值包括:
    • true:请求成功。
    • false:请求失败。
    BOOL
    distance 检索到记录的特征距离。 LIST(FLOAT)
    group_id 检索到的记录的group_id列表。 STRING
    intra_id 检索到的记录的intra_id列表。 INT
    oss_path_name 检索到的记录的原始图片地址。 STRING
    error_code 请求失败时,返回的错误码。 INT
    error_msg 请求失败时,返回的错误信息。 STRING
  • 输出示例
    {
        "request_id": "d74f7fc3-7cac-4986-81db-6010f1b7****", 
        "success": true, 
        "distance": [0.0], 
        "group_id": ["6000"], 
        "intra_id": [0.0],
        "oss_path_name" : [xxxx]
    }

清理数据(clean)

在长期删除数据后,数据库可能会存在一定的检索误差,您可以手动调用数据清理函数,消除误差。以下介绍该接口的调用示例及参数说明:
  • POST内容示例
    {   
        "db_name": "oss_hz",
        "function_name": "clean",
        "function_params": {
         }   
    }
  • 输入参数说明

  • 输出参数说明
    参数 描述 类型
    request_id 请求的唯一标识。 STRING
    success 请求是否成功,取值包括:
    • true:请求成功。
    • false:请求失败。
    BOOL
    clean_db 是否成功调用清除函数,取值包括:
    • true:调用成功。
    • false:调用失败。
    BOOL
    clean_num 清除掉的已经删除了的数据记录的数量。 INT
    cleaned_record_num 清除后,剩余的有效记录数量。 INT
    error_code 请求失败时,返回的错误码。 INT
    error_msg 请求失败时,返回的错误信息。 STRING
  • 输出示例
    {
        "request_id": "dd535e4b-55eb-4ad8-b9c5-009eedef****", 
        "success": true, 
        "clean_db": true, 
        "clean_num": 2,
        "cleaned_record_num": 92 
    }