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

人脸检索服务部署后，数据库管理层提供以下功能： 下文详细介绍数据库管理层提供的接口，此处仅介绍每个接口的特有参数，关于接口中的通用参数说明请参见接口格式及调用说明（必读）。

初始化（init）

如果您已经开通了OSS，则无需进行初始化，具体操作请参见开通OSS后的特有接口。如果您未开通OSS，则需要遵守如下调用规则：
  • 服务部署后，您必须先调用init接口获取uid_key，在后续部分接口的参数中指定uid和uid_key，才能完成调用。
  • 关闭服务后，再次重启服务时，您需要调用init接口并输入自己的uid和uid_key，才能加载服务关闭前的数据库内容。
在此基于Python代码介绍该接口的调用示例及参数说明：
  • 调用示例
    import requests, json
datas = json.dumps({   
            "function_name": "init",
            "function_params": {
                "uid" : 阿里云账号的账号ID,
                "uid_key": 可选，初次init无需填写
            },
        })
head = {"Authorization": "XXXX"} #服务部署成功后返回的Token密钥。
hosts = "xxxxxx/test" #服务的地址。
r = requests.post(hosts, data=datas, headers=head)
  • 输入参数说明
    参数 是否必选 描述 类型
    uid 是 阿里云唯一的账号ID，获取方式请参见如何查看主账号UID？。 STRING
    uid_key 否 初次调用init接口返回的uid_key，重启服务后，需要制定该参数进行登录。 STRING
  • 输出参数说明
    参数 描述 类型
    request_id 请求的唯一标识。 STRING
    uid_key 输入uid后，该接口返回的uid_key。您需要保存该信息，以供后续调用使用。 STRING
    success 请求是否成功，取值包括：
    • true：请求成功。
    • false：请求失败。
    		BOOL
    info 状态提示。当提供uid和uid_key时，返回校验和加载的数据库结果。 STRING
    error_code 请求失败时，返回的错误码。 INT
    error_msg 请求失败时，返回的错误信息。 STRING
  • 输出示例
    {
    "request_id": "7c4c94dc-cf3f-4342-baa8-83382df9****", 
    "success": true, 
    "uid_key": "a6c3ac07c9c33187f2ec9bf04e72****"
  // "info": "uid doesn't match uid_key, init failed!"
}
    上例中两个正斜线（//）注释掉的内容表示可能输出的内容，会根据您不同的输入而变化。

增加数据库（add）

如果您已经开通了OSS，则需要先阅读OSS支持的额外接口（详情请参见开通OSS后的特有接口），再阅读本节内容。如果您未开通OSS，则需要遵守如下调用规则：
  • 调用add接口前，需要调用init接口，以获取uid对应的唯一uid_key，才能顺利使用该接口增加数据库。
  • 每个uid仅能添加5个数据库，如果超过该限制或重复添加，则系统返回提示信息。
以下介绍该接口的调用示例及参数说明：
  • POST内容示例
    {
    "function_name": "add",
    "function_params": {
        "db_name":"oss_hz", # 待添加的数据库名称。
        "uid" : "xxxxxxx", # 阿里云账号的账号ID。
        "uid_key": "a6c3ac07c9c33187f2ec9bf04e72****" # 初始化后返回的uid_key，与uid绑定在一起。
     }
}
  • 输入参数说明
    参数 是否必选 描述 类型
    db_name 是 待添加的检索数据库名称。 STRING
    uid 是 用户唯一的阿里云账号ID，获取方式请参见如何查看主账号UID？ STRING
    uid_key 是 初次调用init接口返回的uid_key。 STRING
  • 输出参数说明
    字段 描述 类型
    request_id 请求的唯一标识。 STRING
    success 请求是否成功，取值包括：
    • true：请求成功。
    • false：请求失败。
    		BOOL
    add 添加成功后，返回添加的数据库相关初始化信息。 DICT
    info 状态提示。例如重复添加会返回提示信息。 STRING
    error_code 请求失败时，返回的错误码。 INT
    error_msg 请求失败时，返回的错误信息。 STRING
  • 输出示例
    {
    "request_id": "da95a008-8cb5-47b0-beb3-c2dd9d27****",
    "success": true,
    "add": {"name": "oss_hz_1", "record_num": 0, "groupid_num": 0, "database_save_path": "oss://xx****/a6c3ac07cxxxxxxbf04e72****/oss_hz_1/RDB.pkl"}
    //"info": "[oss_hz] are in service\'s db_dict"
}
    上例中两个正斜线（//）注释掉的内容表示可能输出的内容，会根据您不同的输入而变化。

删除数据库（delete）

对于公共用户和已经开通OSS的用户，需要遵守如下不同的调用规则：
  • 如果您已经开通了OSS，则需要先调用set接口，设置服务默认的OSS信息，才能使用该接口。set接口的详细信息请参见开通OSS后的特有接口）。
  • 如果您未开通OSS，则调用delete接口前，需要调用init接口，以获取uid对应的唯一uid_key，才能顺利使用该接口删除数据库。
以下介绍该接口的调用示例及参数说明：
  • POST内容示例
    {
    "function_name": "delete",
    "function_params": {
        "db_name":"oss_hz", #待删除的数据库名称。
        "uid" : "xxxxxxx", # 用户阿里云唯一的账号ID。
        "uid_key": "a6c3ac07c9c33187f2ec9bf04e72****" # 初始化后返回的uid_key，与uid绑定在一起。
     }
}
  • 输入参数说明
    参数 是否必选 描述 类型
    db_name 是 待删除的检索数据库名称。 STRING
    uid 是 用户唯一的阿里云账号ID，获取方式请参见如何查看主账号UID？。 STRING
    uid_key 是 初次调用init接口返回的uid_key。 STRING
  • 输出参数说明
    字段 描述 类型
    request_id 请求的唯一标识。 STRING
    success 请求是否成功，取值包括：
    • true：请求成功。
    • false：请求失败。
    		BOOL
    delete 删除是否成功，取值包括：
    • true：删除成功。
    • false：删除失败。
    		BOOL
    info 状态提示，例如重复添加会返回提示信息。 STRING
    error_code 请求失败时，返回的错误码。 INT
    error_msg 请求失败时，返回的错误信息。 STRING
  • 输出示例
    {
    "request_id": "da95a008-8cb5-47b0-beb3-c2dd9d27****", 
    "success": true, 
    "delete" : true,
    //"info": "[oss_hz_1] not in service\'s db_dict" 
}
    上例中两个正斜线（//）注释掉的内容表示可能输出的内容，会根据您不同的输入而变化。

查询数据库（get）

该接口无需您输入uid和uid_key，即可查询当前服务的数据库信息，或查询指定数据库的相关信息。以下介绍该接口的调用示例及参数说明：
  • POST内容示例
    {
    "function_name": "get",
    "function_params": {
        "db_dict": true, # 是否查询服务所有数据库信息。
        "db_name" : "oss_hz",  # 查询指定名称的数据库信息。
     }
}
  • 输入参数说明
    参数 是否必选 描述 类型
    db_name 否 待查询的检索数据库名称 STRING
    db_dict 否 是否查询服务所有数据库信息，取值包括：
    • true：查询服务所有的数据库信息。
    • false：无需查询服务的数据库信息。
    		BOOL
  • 输出参数说明
    参数 描述 Type
    request_id 请求的唯一标识。 STRING
    success 请求是否成功，取值包括：
    • true：请求成功。
    • false：请求失败。
    		BOOL
    db_dict 在输入中，db_dict取值为true时，接口返回服务包含的所有数据库信息。 DICT
    db_name 在输入中，指定db_name时，接口返回对应的数据库信息。 DICT
    error_code 请求失败时，返回的错误码。 INT
    error_msg 请求失败时，返回的错误信息。 STRING
  • 输出示例
    {
    "request_id": "6c95b76f-f9ce-446a-b890-7f76fe75****", 
    "success": true, 
    "db_dict": {"oss_hz": {"name": "oss_hz", "record_num": 0, "groupid_num": 0, "database_save_path": "oss://xxxxx/xxxx7c9c33187f2ec9bf04e72****/oss_hz/RDB.pkl"}}
    //"oss_hz": {"name": "oss_hz", "record_num": 0, "groupid_num": 0, "database_save_path": "oss://xxxxxx/a6c3acxxxxx187f2ec9bf04e72****/oss_hz/RDB.pkl"}
}
    上例中两个正斜线（//）注释掉的内容表示可能输出的内容，会根据您不同的输入而变化。

保存数据库（save）

该接口无需您输入uid和uid_key，即可保存当前服务的所有数据库信息。系统支持如下保存策略：
  • 服务拥有自动保存功能。服务部署后，每天自动保存一次。
  • 服务关闭前，建议您手动调用该接口，保存服务的所有数据库信息。
以下介绍该接口的调用示例及参数说明：
  • POST内容示例
    {
    "function_name": "save",
    "function_params": {
     }
}
  • 输入参数说明

    无

  • 输出参数说明
    参数 描述 类型
    request_id 请求的唯一标识。 STRING
    success 请求是否成功，取值包括：
    • true：请求成功。
    • false：请求失败。
    		BOOL
    save 保存是否成功，取值包括：
    • true：保存成功。
    • false：保存失败。
    		BOOL
    error_code 请求失败时，返回的错误码。 INT
    error_msg 请求失败时，返回的错误信息。 STRING
  • 输出示例
    {
"request_id": "6c95b76f-f9ce-446a-b890-7f76fe75****", 
"success": true, 
"save" : true
}