检索服务的数据库管理层支持对管理的数据库进行增加、删除、查询及保存操作。本文介绍各操作接口的详细信息，包括输入参数、输出参数及调用示例。

背景信息

服务部署后，数据库接口支持对数据库进行增加、删除、查询及保存操作，具体的接口列表如下：

初始化（init）

通过初始化接口设置OSS后端的存储和检索，您需要提前开通OSS服务，并提供相关配置（包括AccessKey ID,、AccessKey Secret、Endpoint及Buckets）。初始化接口的详细信息如下：
  • 输入参数说明
    参数 是否必选 描述 示例值 类型
    root_path 是 注册数据和特征的OSS存储地址。 "oss://ev-retrieval-data/xxx/" STRING
    oss_io_config 是 OSS的相关配置。您需要保证该配置可以访问到root_path，且具有写权限。该参数的取值格式为oss_io_config = dict(ak_id='<yourAccessKeyId>',ak_secret='<yourAccessKeySecret>',hosts='<yourHost>',buckets=['<yourBucket>'])，您需要将如下字段替换为实际值，其他部分使用上述的固定值：
    • <yourAccessKeyId>：阿里云账号的AccessKey ID。
    • <yourAccessKeySecret>：阿里云账号的AccessKey Secret。
    • <yourHost>：您OSS地域的Endpoint。OSS地域与Endpoint的对应关系，请参见公共云下OSS Region和Endpoint对照表。
    • <yourBucket>：您创建的OSS存储空间（Bucket）的名称。 
    oss_io_config = dict(ak_id='xxx',ak_secret='xxxx',hosts='oss-cn-zhangjiakou.aliyuncs.com',buckets=['ev-retrieval-data'])
    		 DICT
  • 输出参数说明
    参数 描述 示例值 类型
    status 请求是否成功，取值包括：
    • true：请求成功。
    • false：请求失败。
    		true BOOL
    info 请求成功后返回执行内容的相关提示。 init db success. STRING
    error_code 请求失败时，返回的错误码。 None INT
    error_msg 请求失败时，返回的错误信息。 None STRING
  • 示例
    以下为Python代码调用接口的示例。
    import requests, json
our_oss_io_config = dict(ak_id='xxxxxx', 
                ak_secret='xxxxxx', 
                hosts='oss-cn-hangzhou.aliyuncs.com', 
                buckets='pai-vision-data-hz')

datas = json.dumps({
        "input": {   
            "function_name": "init",
            "function_params": {
                "root_path": "oss://pai-vision-data-hz/xxx",
                "oss_io_config" : our_oss_io_config,
            }}
        })
head = {"Authorization": "XXXX"} #服务部署成功后，PAI-EAS返回的Token密钥。
hosts = "xxxxxx/test"  #服务部署成功后，PAI-EAS返回的服务地址。
r = requests.post(hosts, data=datas, headers=head)

添加特征数据库（add）

您可以指定数据库名称，通过该接口添加特征数据库。以下介绍该接口的参数说明及调用示例：
  • 输入参数说明
    参数 是否必选 描述 示例值 类型
    database_name 是 待添加的检索数据库名称。 "" STRING
    feature_dim_dict 否 特征维度。 {} DICT
    feature_distance_dict 否 特征距离函数，取值包括：
    • SquaredEuclidean：平方欧式距离。
    • Cosine：余弦距离。
    		{} DICT
  • 输出参数说明
    参数 描述 示例值 类型
    status 数据库是否添加成功，取值包括：
    • true：添加成功。
    • false：添加失败。
    		true BOOL
    name 添加成功后，返回数据库名称。 "test" STRING
    info 状态提示。例如重复添加数据库，接口返回提示信息。 "" STRING
    error_code 请求失败时，返回的错误码。 None INT
    error_msg 请求失败时，返回的错误信息。 None STRING
  • 示例
    以下为Python代码调用接口的示例。
    import requests, json

datas = json.dumps({
            "input": {
                "function_name": "add",
                "function_params": {
                    "database_name": "test_0428",
                    "feature_dim_dict": {"feature": 2},
                                        "feature_distance_dict": {"feature":"Cosine"},
                },
            }})
head = {"Authorization": "XXXX"} #服务部署成功后，PAI-EAS返回的Token密钥。
hosts = "xxxxxx/test"  #服务部署成功后，PAI-EAS返回的服务地址。
r = requests.post(hosts, data=datas, headers=head)

查询特征数据库（get）

您可以通过该接口查询当前服务下的所有特征数据库的信息，也可以指定数据库名称，查询特定数据库的信息。以下介绍该接口的调用示例及参数说明：
  • 输入参数说明
    参数 是否必选 描述 示例值 类型
    database_name 否 需要查询的检索数据库的名称。 "test" STRING
    verbose 是 返回的数据库信息是否包含详细信息，取值包括：
    • True：返回详细信息。
    • False：仅返回数据库包含的record _num数目。
    		False BOOL
    get_all 是 是否查询服务的所有数据库，取值包括：
    • True：返回所有数据库信息，此时无需指定database_name。
    • False：仅查询database_name指定的数据库信息。
    		False BOOL
  • 输出参数说明
    参数 描述 示例值 Type
    success 请求是否成功，取值包括：
    • true：请求成功。
    • false：请求失败。
    		true BOOL
    info 查询所有数据库，返回的内容列表。 [{"name": "test_0428", "status": true, "record_num": 0}] LIST
    error_code 请求失败时，返回的错误码。 None INT
    error_msg 请求失败时，返回的错误信息。 None STRING
  • 示例
    以下为Python代码调用接口的示例。
    import requests, json
datas = json.dumps({
            "input": {
                "function_name": "get",
                "function_params": {
                    "database_name": "test_0428",
                    "get_all": False,
                    "verbose": False
                },
            }})
head = {"Authorization": "XXXX"} #服务部署成功后，PAI-EAS返回的Token密钥。
hosts = "xxxxxx/test"  #服务部署成功后，PAI-EAS返回的服务地址。
r = requests.post(hosts, data=datas, headers=head)

删除特征数据库（delete）

您可以指定数据库名称，通过该接口删除指定的特征数据库，以下介绍该接口的参数说明及调用示例：
  • 输入参数说明
    参数 是否必选 描述 示例值 类型
    database_name 是 待删除的检索数据库名称。 "test" STRING
  • 输出参数说明
    参数 描述 示例值 类型
    success 请求是否成功，取值包括：
    • true：请求成功。
    • false：请求失败。
    		true BOOL
    status 删除是否成功，取值包括：
    • true：删除成功。
    • false：删除失败。
    		true BOOL
    name 删除的数据库的名称。 "test" STRING
    info 状态提示。例如重复删除数据库，接口返回提示信息。 {"acknowledged": true} DICT/STRING
    error_code 请求失败时，返回的错误码。 None INT
    error_msg 请求失败时，返回的错误信息。 None STRING
  • 示例
    以下为Python代码调用接口的示例。
    import requests, json

datas = json.dumps({
            "input": {
                "function_name": "delete",
                "function_params": {
                    "database_name": "test_0428",
                },
            }})
head = {"Authorization": "XXXX"} #服务部署成功后，PAI-EAS返回的Token密钥。
hosts = "xxxxxx/test"  #服务部署成功后，PAI-EAS返回的服务地址。
r = requests.post(hosts, data=datas, headers=head)

保存特征数据库（save）

对于OSS用户，每一个特征数据库需要在添加特征后手动保存，相关特征数据库会保存在初始化时设置的root_path中。以下介绍该接口的调用示例及参数说明：
  • 输入参数说明
    参数 是否必选 描述 示例值 类型
    database_name 否 待保存的检索数据库名称。

    如果不填写该参数，或填写的数据库不存在，则默认保存服务中所有的特征数据库。

    		 "test" STRING
  • 输出参数说明
    参数 描述 示例值 类型
    success 请求是否成功，取值包括：
    • true：请求成功。
    • false：请求失败。
    		true BOOL
    info 保存是否成功，取值包括：
    • true：保存成功。
    • false：保存失败。
    		true BOOL
    error_code 请求失败时，返回的错误码。 None INT
    error_msg 请求失败时，返回的错误信息。 None STRING
  • 示例
    以下为Python代码调用接口的示例。
    import requests, json

datas = json.dumps({
            "input": {
                "function_name": "save",
                "function_params": {
                    "database_name": "test_0428",
                },
            }})
head = {"Authorization": "XXXX"} #服务部署成功后，PAI-EAS返回的Token密钥。
hosts = "xxxxxx/test"  #服务部署成功后，PAI-EAS返回的服务地址。
r = requests.post(hosts, data=datas, headers=head)