全量数据服务

注意事项

使用全量数据服务API过程中，会存在如下约束与限制：

• 单次调用全量数据服务API的请求参数总量不能＞500KB。
• 单次调用全量数据服务中的API，其Body里参数对象（一对{}算一个对象）总数不能大于20000个。
• 调用全量数据服务API时，整型/长整型类型属性默认使用强校验。即，当整型/长整型类型属性的入参不是整数时（例如输入浮点数值），系统将不再自动向下取整，而是返回校验失败的错误提示。
• 在支持分页查询的接口中，系统允许每页返回数据行数（pageSize参数）最大限制默认为5000行。建议您合理设置pageSize值大小（例如<200），以避免多并发查询时可能会导致CPU使用率升高影响使用体验。
• 为保障您的应用安全性，在调用数据实体和关系实体相关分页查询接口时存在如下约束与限制：
  • 如果分页偏移量＞5万，受限于数据库分页查询效能，可能存在响应时长增加的情况，为保障查询体验，建议list、find、query和select等接口的分页偏移量≤5万。
  • 如果分页偏移量＞50万，对应分页查询接口将自动触发限流保护，提示“当前已触发分页查询限流保护，请稍后重试。”。
• 如果入参参数为Collection、map或Array类型，单次最多传入1000个对应类型的参数值。
• 枚举、分类、JSON、参考对象、浮点型（自定义精度）和文件类型属性的入参值不允许为空字符串；文本、长文本、URL和人员类型属性的入参值允许为空字符串，返回结果会返回该空字符串。
• 如果输入的浮点型（自定义精度）类型属性值超过自定义标度，会先四舍五入到指定标度后再校验。
• 如果存在“多值”为“是”的枚举类型扩展属性，入参不允许输入[""]。
• 如果您想将数据实例中自定义的属性（包括基本属性和扩展属性）设置为空值，可在调用数据实体/关系实体的update、batchUpdate、save、saveAs和saveAll接口时，在“needSetNullAttrs”参数中对非必填属性进行设置。
• 调用数据实体/关系实体的创建类接口（如create、batchCreate、save、saveAs和saveAll）时，
  • 已设置默认值的属性未输入入参值，返回结果会返回该默认值。
  • 未设置默认值的整型、长整型、浮点型、日期和布尔值类型属性，如果入参值为空字符串，返回结果会返回空值（即NULL）。
• 调用数据实体/关系实体的更新类接口（如updateByAdmin、update、reviseAndUpdate、checkoutAndUpdate、updateAndCheckin、updateByCondition、save、saveAll、batchUpdateByAdmin、batchReviseAndUpdate、batchCheckoutAndUpdate和batchUpdateAndCheckin）时，
  • 如果存在“值可变”为“否”的属性，其返回结果会返回原值。
  • 整型、长整型、浮点型、日期和布尔值类型属性，如果入参值为空字符串，返回结果会返回原值。
• 调用save和saveAs接口时，如果入参值为NULL或未输入入参值，其返回结果会返回原值。
• 调用saveAll接口时，基本属性的入参值会强覆盖，扩展属性的入参值不会强覆盖。即：如果基本属性未输入入参值，其返回结果会返回NULL；如果扩展属性未输入入参值，其返回结果会返回原值。
• 调用find接口查询“入库”为“否”的属性时，如果对应属性未设置默认值，其返回结果会返回NULL。

查看全量数据服务API详情

为了方便用户查看API信息，xDM-F提供如下查看方式：

• 离线方式：将全量数据服务API导出至本地计算机进行查看（推荐），具体操作请参见导出全量数据服务API。
• 在线方式：
  • 在应用运行态的“数据服务管理 > 全量数据服务”页查看所有全量数据服务API的信息。
    图1 全量数据服务API
    

    在该页面中，您可以查看到的全量数据服务API包括：数据实体、关系实体、搜索服务及系统管理API。

  • 在“数据实体”折叠面板上查看某个数据实体的所有API信息，及其数据实体下某个具体API的详细信息。

    展开“数据实体”折叠面板，通过对应数据实体英文名称进入API列表页。

    图2 数据实体API列表
    

    在该页面，您可以查看到对应数据实体的所有对外可调用API，还可以通过对应“API英文名称”超链接进入API详情页。

  • 在“关系实体”折叠面板上查看某个关系实体的所有API信息，及其关系实体下某个具体API的详细信息。

    展开“关系实体”折叠面板，通过对应关系实体英文名称进入API列表页。

    图3 关系实体API列表
    

    在该页面中，您可以查看到对应关系实体的所有对外可调用API，还可以通过对应“API英文名称”超链接进入API详情页。

  • 在“搜索服务”折叠面板上查看某个搜索服务定义的所有API信息，及其搜索服务定义下某个具体API的详细信息。

    展开“搜索服务”折叠面板，通过对应搜索服务英文名称进入API列表页。

    在该页面中，您可以查看到对应搜索服务的所有对外可调用API，还可以通过对应“API英文名称”超链接进入API详情页。

  • 在“系统管理API”折叠面板上查看所有系统功能的信息，及其系统功能下某个具体API的详细信息。

    展开“系统管理API”折叠面板，您可以查看到的系统管理API包括：数据实例鉴权、XDM基线对象、基线对象与被基线对象的关系、分类管理、分类节点的分组、数据清理与重置、数据实体&关系实体授权、实体信息管理、文件管理、文件夹、初始化异常、数据实例授权及租户等。此外，您还可以通过对应“API英文名称”超链接进入API详情页。

    图4 系统管理API列表
    

搜索全量数据服务API

默认情况下，全量数据服务页展示的是当前应用下所有对外可调用的全量数据服务API。为了帮助用户快速搜索出当前应用下对外可调用的全量数据服务API，xDM-F提供搜索全量数据服务API功能，您在搜索框中输入关键字后，即可快速对全量数据服务API展开检索。

1. 在左侧导航栏中，单击“数据服务管理 > 全量数据服务”，进入“全量数据服务”页面。
2. 在“全量数据服务”的“分类”操作栏中，根据实际需求，直接在搜索框中输入需要搜索的API英文名称，单击。
   图5 搜索API
   

导出全量数据服务API

xDM-F提供全量数据服务API导出功能，您可以导出整个应用的全部API或者部分API，便于您在本地计算机中查阅。

1. 在左侧导航栏中，选择“数据服务管理 > 全量数据服务”，进入“全量数据服务”页面。
2. 在“全量数据服务”的“分类”操作栏中，您可以通过如下方式导出全量数据服务API。
   • 全部导出：单击“导出批量操作 > 全部导出”。
     图6 全部导出
     
   • 导出选中项：勾选需要导出的API或分类，单击“导出批量操作 > 导出选中项”。
     图7 导出选中项
     

3. 在弹出的窗口中，选择导出文件的保存路径，单击“保存”。

   “swagger.zip”文件即为导出的全量数据文件，该压缩文件包含custom_service.yaml、entities.yaml、search_service.yaml和system_endpoint.yaml。推荐使用Swagger编辑器打开导出的yaml文件。

   • entities.yaml：存放数据实体API和关系实体API。
   • search_service.yaml：存放搜索服务定义API。
   • system_endpoint.yaml：存放系统管理API。