分析工作区数据提取 API
功能¶
从分析工作区分区中提取数据。
URL¶
<api-root>/aih/data/v1/database_id/workspace_code/
如果应用程序配置为管理 GDPR/DAC6 法规，则启用了个人数据保护选项的分析工作区数据值将以加密形式导出。
功能¶
- 物理数据集
- 虚拟数据集
- 数据源
所有功能均与指定分析工作区的报表层数据相关。
对于每个功能，系统可能要求为流程、场景、期间和实体指定筛选参数，以限制返回的数据量。请求将取决于数据集中是否存在以下元素：
- 分区类型
- 是否存在场景、期间和实体维度的列。
返回的数据受用户对场景、期间和实体维度的可见性限制约束。
参数¶
非分区数据集/虚拟数据集或数据源¶
数据从唯一存在的分区中读取，并可能根据是否存在与场景、期间和实体维度相关的字段进行筛选。
| 参数 | 是否必填 | 描述 |
|---|---|---|
| 流程 | 可选 | 如果定义，必须始终使用代码（例如 $PROCESS）。 |
| 场景 | 仅当数据集中定义了场景维度的列时才必填。仅当数据集中定义了场景维度的列时才必填。 | 可使用以下方式定义： - 代码（例如 001） - 以逗号分隔的代码列表（例如 001,002,003） - 值 $ALL 以告知系统选择所有值 |
| 期间 | 仅当数据集中定义了期间维度的列时才必填。仅当数据集中定义了期间维度的列时才必填。 | 可使用以下方式定义： - 代码（例如 001） - 以逗号分隔的代码列表（例如 001,002,003） - 值 $ALL 以告知系统选择所有值 |
| 实体 | 仅当数据集中定义了实体维度的列时才必填。仅当数据集中定义了实体维度的列时才必填。 | 在数据集中，可使用以下方式定义： - 代码（例如 001） - 以逗号分隔的代码列表（例如 001,002,003） - 值 $ALL 以告知系统选择所有值 在虚拟数据集中，只能使用单个代码定义。 |
按业务周期分区的数据集/虚拟数据集¶
数据从与分配给流程、场景和期间参数的值相对应的分区中读取，并可能根据与场景、期间和实体维度相关的字段进行筛选。如果所选流程是单次提交流程，则场景和期间参数的值不用于获取要读取的分区。
| 参数 | 是否必填 | 描述 |
|---|---|---|
| 流程 | 必填 | 必须始终使用代码定义（例如 $PROCESS）。 |
| 场景 | 必填 | 可使用以下方式定义： - - 代码（例如 001） - 以逗号分隔的代码列表（例如 001,002,003） - 值 $ALL 以告知系统选择所有值 |
| 期间 | 必填 | 可使用以下方式定义： - - 代码（例如 001） - 以逗号分隔的代码列表（例如 001,002,003） - 值 $ALL 以告知系统选择所有值 |
| 实体 | 仅当数据集中定义了实体维度的列时才必填。 | 在数据集中，可使用以下方式定义： - - 代码（例如 001） - 以逗号分隔的代码列表（例如 001,002,003） - 值 $ALL 以告知系统选择所有值 在虚拟数据集中，只能使用单个代码定义。 |
按业务周期和实体分区的数据集和虚拟数据集¶
数据从与分配给流程、场景和期间参数的值相对应的分区中读取，并可能根据与场景、期间和实体维度相关的字段进行筛选。如果所选流程是单次提交流程，则场景和期间参数的值不用于获取要读取的分区。
| 参数 | 是否必填 | 描述 |
|---|---|---|
| 流程 | 必填 | 必须始终使用代码定义（例如 $PROCESS）。 |
| 场景 | 必填 | 可使用以下方式定义： - - 代码（例如 001） - 以逗号分隔的代码列表（例如 001,002,003） - 值 $ALL 以告知系统选择所有值 |
| 期间 | 必填 | 可使用以下方式定义： - - 代码（例如 001） - 以逗号分隔的代码列表（例如 001,002,003） - 值 $ALL 以告知系统选择所有值 |
| 实体 | 必填 | 在数据集中，可使用以下方式定义： - - 代码（例如 001） - 以逗号分隔的代码列表（例如 001,002,003） - 值 $ALL 以告知系统选择所有值 - 在虚拟数据集中，只能使用单个代码定义。 |
按功能检查参数的请求¶
返回数据集功能的必填参数列表：
<api-root>/aih/metadata/v1/database_id/workspace_code/dataset_code/Parameters
示例¶
与物理数据集相关的示例可通过将语法 Dataset 替换为 VirtualDataset 应用于虚拟数据集。
例如，Dataset_000001(Scenario='2020ACT',Period='12',Entity='001') 变为 VirtualDataset_000001(Scenario...)。
对于数据源，语法类似（Datasource_000001(Scenario...)），但由于没有数据分区，提取逻辑有所不同。
| 参数 | URL | 描述 |
|---|---|---|
| 非分区数据集 | ||
| 无 | <api-root>/data/v1/TGK_APP/001/Dataset_000001() |
从唯一存在的分区中读取未筛选的数据。 |
| 带场景、期间和实体字段的非分区数据集 | ||
| - 场景 - 期间 - 实体 | <api-root>/aih/data/v1/TGK_APP/001/Dataset_000001(Scenario='2020ACT',Period='12',Entity='001') |
从唯一存在的分区中读取按场景、期间和实体筛选的数据。 |
| 在单次提交流程中按业务周期分区的数据集 | ||
| - 流程 - 场景 - 期间 | <api-root>/aih/data/v1/TGK_APP/001/Dataset_000001(Process='BUDGET',Scenario='2020BDG',Period='12') |
从所选流程唯一存在的分区中读取数据，忽略场景和期间筛选器。 |
| 在单次提交流程中带场景和期间字段的按业务周期分区的数据集 | ||
| - 流程 - 场景 - 期间 | <api-root>/aih/data/v1/TGK_APP/001/Dataset_000001(Process='BUDGET',Scenario='2020BDG',Period='12') |
从所选流程唯一存在的分区中读取按场景和期间筛选的数据。 |
| 在单次提交流程中带场景、期间和实体字段的按业务周期分区的数据集 | ||
| - 流程 - 场景 - 期间 - 实体 | <api-root>/aih/data/v1/TGK_APP/001/Dataset_000001(Process='BUDGET',Scenario='2020BDG',Period='12',Entity='001') |
从所选流程唯一存在的分区中读取按场景、期间和实体筛选的数据。 |
| 在场景/期间提交流程中按业务周期分区的数据集 | ||
| - 流程 - 场景 - 期间 | <api-root>/aih/data/v1/TGK_APP/001/Dataset_000001(Process='ACTUAL',Scenario='2020ACT',Period='12') |
从所选流程、场景和期间唯一存在的分区中读取未筛选的数据。 |
| 在场景/期间提交流程中带实体字段的按业务周期分区的数据集 | ||
| - 流程 - 场景 - 期间 - 实体 | <api-root>/aih/data/v1/TGK_APP/001/Dataset_000001(Process='ACTUAL',Scenario='2020ACT',Period='12',Entity='001') |
从所选流程、场景和期间唯一存在的分区中读取按实体筛选的数据。 |
| 在单次提交流程中按业务周期和实体分区的数据集 | ||
| - 流程 - 场景 - 期间 - 实体 | <api-root>/aih/data/v1/TGK_APP/001/Dataset_000001(Process='BUDGET',Scenario='2020BDG',Period='12',Entity='001') |
从所选流程和实体唯一存在的分区中读取数据，忽略场景和期间筛选器。 |
| 在单次提交流程中带场景和期间字段的按业务周期和实体分区的数据集 | ||
| - 流程 - 场景 - 期间 - 实体 | <api-root>/aih/data/v1/TGK_APP/001/Dataset_000001(Process='BUDGET',Scenario='2020BDG',Period='12',Entity='001') |
从所选流程和实体唯一存在的分区中读取按场景和期间筛选的数据。 |
| 通过选择场景/期间提交流程按业务周期和实体分区的数据集 | ||
| - 流程 - 场景 - 期间 - 实体 | <api-root>/aih/data/v1/TGK_APP/001/Dataset_000001(Process='ACTUAL',Scenario='2020ACT',Period='12',Entity='001') |
从所选流程、场景、期间和实体唯一存在的分区中读取未筛选的数据。 |
| 带场景、期间和实体字段的数据源 | ||
| - 场景 - 期间 - 实体 | <api-root>/aih/data/v1/TGK_APP/001/Datasource_000003(Scenario='2016BDG',Period='12',Entity='001) |
读取按所选场景、期间和实体筛选的数据。 |
| 不带场景、期间或实体字段的数据源 | ||
| 无 | <api-root>/aih/data/v1/TGK_APP/001/Datasource_000003() |
读取未筛选的数据。 |
OData 查询选项¶
下面提供了支持的 OData 查询选项列表。
| 示例 | 描述 |
|---|---|
| $count | |
| http://127.0.0.1:8080/tagetikcpm/api/aih/data/v1/TGK_APP/001/Datasource_000003()?$count=true | 返回 @odata.count 注释中的记录数，但不返回记录值。 |
| $top | |
| http://127.0.0.1:8080/tagetikcpm/api/aih/data/v1/TGK_APP/001/Datasource_000003()?$top=100 | 返回前 100 条记录。 |
| $skip | |
| http://127.0.0.1:8080/tagetikcpm/api/aih/data/v1/TGK_APP/001/Datasource_000003()?$top=100&$skip=50 | 仅返回从第 51 条记录开始的前 100 条记录。此选项不能在没有 $top 选项的情况下使用。 |
| $orderby | |
| http://127.0.0.1:8080/tagetikcpm/api/aih/data/v1/TGK_APP/001/Datasource_000003()?$orderby=Account desc,Entity asc | 返回按科目和实体排序的记录。如果同时使用 $top 和 $skip 选项（数据包传输模式），建议使用此选项，以指示要遵循的顺序，从而既提高读取性能，又防止在不同数据包中多次传输单条记录。 |
| $select | |
| http://127.0.0.1:8080/tagetikcpm/api/aih/data/v1/TGK_APP/001/Datasource_000003()?$select=Scenario,Period,Entity,Account,Amount | 对于每条记录，仅返回与场景、期间、实体和金额字段相关的值。这样可以选择仅必要的信息，从而提高性能（传输时间和 CCH Tagetik 应用服务器分配的内存）。 |
| $filter | |
| http://127.0.0.1:8080/tagetikcpm/api/aih/data/v1/TGK_APP/001/Datasource_000003()?$filter=Account eq '001' a Amount ne 0 | 对于每条记录，仅返回科目 = 01 且金额 ≠ 0 的值。 |
$filter 详细信息¶
筛选值取决于要筛选的字段类型：
- 对于文本字段，值必须用单引号（上标）括起来，
- 对于数值字段，值不得用引号括起来，
- 对于时间戳字段，值不得用引号括起来，并且必须使用格式 yyyy-mm-ddThh:mi:ssZ（例如 2021-01-01T23:45:12Z）或 yyyy-mm-ddThh:mi:ss.fffZ（例如 2021-01-01T02:08:06.123Z）表示。指示的值必须为 UTC（协调世界时）。
以下是所管理运算符的详细信息：
| 运算符 | 描述 | 示例 |
|---|---|---|
| Eq | 等于 | /Suppliers?$filter=Address/City eq 'Redmond' |
| In | 包含于 | /Suppliers?$filter=Address/City in ('Redmond','London') |
| Ne | 不等于 | /Suppliers?$filter=Address/City ne 'London' |
| Gt | 大于 | /Products?$filter=Price gt 20 |
| Ge | 大于或等于 | /Products?$filter=Price ge 10 |
| Lt | 小于 | /Products?$filter=Price lt 20 |
| Le | 小于或等于 | /Products?$filter=Price le 100 |
| And | 逻辑与 | /Products?$filter=Price le 200 and Price gt 3.5 |
| Or | 逻辑或 | /Products?$filter=Price le 3.5 or Price gt 200 |
| Not | 逻辑非 | /Products?$filter=not (Address/City eq 'Redmond') |
其他参数¶
可以指定自定义参数 numberFormat，用于控制数值字段使用的数据类型：如果参数值为 double，将使用 Double 类型；如果参数值为 decimal，将使用 Decimal 类型
如果未指定该参数，将使用 Double 类型。
用法示例：
http://127.0.0.1:8080/tagetikcpm/api/aih/data/v1/TGK_APP/001/Datasource_000003()?numberFormat=decimal
重要：API 调用具有不可修改的 10 分钟超时。为避免达到此超时，可以通过应用以下一种或多种策略来减少单个 API 调用检索的数据量：
- 如果服务具有输入参数（流程、场景、期间、实体），建议指定一个或多个值，而不是通过 '$ALL' 语法选择所有值。
- 如果不需要数据集中的所有字段，可以使用查询选项中的 select 语法提取子集（例如 ?$select=OID,ACCOUNT,COST_CENTER）
- 要进一步限制数据，可以使用查询选项中的 filter 语法（例如 ?$filter=Account eq '01'）
- 对于大量数据，可以在查询选项中使用客户端分页（例如 ?$top=1000&$skip=1000）