计划端点
计划是一种可用于每天自动运行一次批处理分段作业的工具。 您可以使用/config/schedules端点检索计划列表、创建新计划、检索特定计划的详细信息、更新特定计划或删除特定计划。
快速入门
本指南中使用的端点是Adobe Experience Platform Segmentation Service API的一部分。 在继续之前,请查看快速入门指南以了解成功调用API所需了解的重要信息,包括所需的标头以及如何读取示例API调用。
检索计划列表 retrieve-list
您可以通过向/config/schedules端点发出GET请求来检索组织的所有计划的列表。
API格式
/config/schedules端点支持多个查询参数以帮助筛选结果。 虽然这些参数是可选的,但强烈建议使用这些参数以帮助减少昂贵的开销。 在不使用参数的情况下对此端点进行调用将检索对您的组织可用的所有计划。 可以包含多个参数,以&符号(&)分隔。
GET /config/schedules
GET /config/schedules?{QUERY_PARAMETERS}
查询参数
| table 0-row-3 1-row-3 2-row-3 | ||
|---|---|---|
| 参数 | 描述 | 示例 |
start |
指定偏移将从哪一页开始。 默认情况下,该值将为0。 | start=5 |
limit |
指定返回的计划数。 默认情况下,该值将为100。 | limit=20 |
请求
以下请求将检索您组织内发布的最近十个计划。
| code language-shell |
|---|
|
响应
成功的响应会返回HTTP状态200,并将指定组织的计划列表作为JSON返回。
| code language-json |
|---|
|
| table 0-row-2 1-row-2 2-row-2 3-row-2 4-row-2 5-row-2 6-row-2 7-row-2 8-row-2 9-row-2 10-row-2 11-row-2 12-row-2 13-row-2 14-row-2 15-row-2 | |
|---|---|
| 属性 | 描述 |
_page.totalCount |
返回的计划总数。 |
_page.pageSize |
计划的页面大小。 |
children.id |
计划的ID。 |
children.imsOrgId |
计划的组织ID。 |
children.sandbox |
包含计划的沙盒信息的对象。 |
children.name |
作为字符串的计划名称。 |
children.state |
包含计划状态的字符串。 支持的两种状态分别为“活动”和“不活动”。 默认情况下,状态设置为“不活动”。 |
children.type |
字符串形式的作业类型。 两种受支持的类型是batch_segmentation和export。 |
children.schedule |
包含作业计划的字符串。 作业只能被安排每天运行一次,这意味着您不能将作业安排在24小时期间运行多次。 有关cron计划的详细信息,请阅读cron表达式格式的附录。 在此示例中,“0 0 1 * *”表示此计划将在每天凌晨1:00运行。 |
children.frequency |
计划运行的频率。 可能的值包括daily、weekly、monthly和yearly。 |
children.properties |
包含与计划相关的其他属性的对象。 |
children.properties.segments |
属于计划的区段定义的ID。 |
children.owner |
计划的所有者。 可能的值包括user(如果计划由用户创建)和system(如果计划由系统创建)。 |
children.createEpoch |
计划的epoch创建时间(秒)。 |
children.updateEpoch |
上次更新计划的epoch时间(秒)。 |
创建新计划 create
您可以通过向/config/schedules端点发出POST请求来创建新计划。
API格式
POST /config/schedules
请求
| code language-shell |
|---|
|
| table 0-row-2 1-row-2 2-row-2 3-row-2 4-row-2 5-row-2 6-row-2 | |
|---|---|
| 属性 | 描述 |
name |
必需。 作为字符串的计划名称。 |
type |
必需。 字符串形式的作业类型。 两种受支持的类型是batch_segmentation和export。 |
properties |
必需。 包含与计划相关的其他属性的对象。 |
properties.segments |
当type等于“batch_segmentation”时必需。 要包含在计划中的区段定义的ID。 |
schedule |
必需。 包含作业计划的字符串。 作业只能被安排每天运行一次,这意味着您不能将作业安排在24小时期间运行多次。 作业调度将决定调度频率。 有关cron计划的详细信息,请阅读cron表达式格式的附录。 在此示例中,“0 0 1 * *”表示此计划将在每天凌晨1:00运行。 |
state |
可选。 包含计划状态的字符串。 两个支持的状态是active和inactive。 默认情况下,状态设置为inactive。 |
响应
成功的响应返回HTTP状态200以及新创建计划的详细信息。
| code language-json |
|---|
|
| table 0-row-2 1-row-2 2-row-2 3-row-2 4-row-2 5-row-2 6-row-2 7-row-2 8-row-2 9-row-2 10-row-2 11-row-2 12-row-2 13-row-2 14-row-2 15-row-2 16-row-2 | |
|---|---|
| 属性 | 描述 |
id |
新创建的计划的ID。 |
imsOrgId |
创建计划的用户的组织ID。 |
sandbox |
包含计划的沙盒信息的对象。 有关沙箱的详细信息,请阅读沙箱概述。 |
sandbox.sandboxId |
包含您的计划的沙盒的ID。 |
sandbox.sandboxName |
包含您的计划的沙盒的名称。 |
sandbox.type |
沙盒的类型。 可能的值包括production和development。 |
sandbox.default |
一个布尔值,显示沙盒是否为默认沙盒。 |
name |
您为计划提供的名称。 |
state |
计划的状态。 可能的值包括active和inactive。 如果您没有将此设置为请求正文的一部分,则状态将设置为inactive。 |
type |
计划的作业类型。 可能的值包括batch_segmentation和export。 |
schedule |
表示计划运行时间的cron表达式。 有关创建cron表达式的详细信息,请阅读cron表达式格式部分。 |
frequency |
计划运行的频率。 这直接取决于时间表的cron表达式。 可能的值包括daily、weekly、monthly和yearly。 |
properties |
包含计划的区段定义ID的对象(如果计划的类型为batch_segmentation)。 |
owner |
拥有该计划的实体的类型。 由于您创建了计划,因此该值为user。 |
createEpoch |
计划的epoch创建时间(秒)。 |
updateEpoch |
上次更新计划的epoch时间(秒)。 |
检索特定计划 get
您可以通过向/config/schedules端点发出GET请求并在请求路径中提供要检索的调度的ID,来检索有关特定调度的详细信息。
API格式
GET /config/schedules/{SCHEDULE_ID}
{SCHEDULE_ID}id值。请求
| code language-shell |
|---|
|
响应
成功的响应返回HTTP状态200,其中包含有关指定调度的详细信息。
| code language-json |
|---|
|
| table 0-row-2 1-row-2 2-row-2 3-row-2 4-row-2 5-row-2 6-row-2 7-row-2 8-row-2 9-row-2 10-row-2 11-row-2 12-row-2 13-row-2 14-row-2 15-row-2 16-row-2 17-row-2 | |
|---|---|
| 属性 | 描述 |
id |
计划的ID。 |
imsOrgId |
计划所属的组织的ID。 |
sandbox |
包含计划的沙盒信息的对象。 有关沙箱的详细信息,请阅读沙箱概述。 |
sandbox.sandboxId |
包含您的计划的沙盒的ID。 |
sandbox.sandboxName |
包含您的计划的沙盒的名称。 |
sandbox.type |
沙盒的类型。 可能的值包括production和development。 |
sandbox.default |
一个布尔值,显示沙盒是否为默认沙盒。 |
name |
作为字符串的计划名称。 |
state |
包含计划状态的字符串。 两个支持的状态是active和inactive。 默认情况下,状态设置为inactive。 |
type |
字符串形式的作业类型。 两种受支持的类型是batch_segmentation和export。 |
schedule |
包含作业计划的字符串。 作业只能被安排每天运行一次,这意味着您不能将作业安排在24小时内运行多次。 有关cron计划的详细信息,请阅读cron表达式格式的附录。 在此示例中,“0 0 1 * *”表示此计划将在每天凌晨1:00运行。 |
frequency |
计划运行的频率。 此值直接取决于计划的cron表达式。 可能的值包括daily、weekly、monthly和yearly。 |
properties |
包含与计划相关的其他属性的对象。 |
properties.segments |
作为计划一部分的区段定义ID列表。 |
owner |
拥有该计划的实体的类型。 如果用户创建了计划,则此值为user。 如果计划是由系统创建的计划,则此值为system。 |
createEpoch |
计划的epoch创建时间(秒)。 |
updateEpoch |
上次更新计划的epoch时间(秒)。 |
更新特定计划的详细信息 update
您可以更新特定计划,方法是向/config/schedules端点发出PATCH请求,并在请求路径中提供您尝试更新的计划的ID。
API格式
PATCH /config/schedules/{SCHEDULE_ID}
{SCHEDULE_ID}id值。您可以使用JSON修补程序操作来更新计划的状态。 要更新状态,请将path属性声明为/state并将value设置为active或inactive。 有关JSON修补程序的详细信息,请阅读JSON修补程序文档。
请求
| accordion | ||
|---|---|---|
| 更新计划状态的示例请求。 | ||
|
| table 0-row-2 1-row-2 2-row-2 | |
|---|---|
| 属性 | 描述 |
path |
要修补的值的路径。 在这种情况下,由于您正在更新计划的状态,因此需要将path的值设置为“/state”。 |
value |
计划状态的更新值。 此值可设置为“活动”或“不活动”以激活或停用计划。 请注意,如果组织已启用流式传输,则您 无法 禁用计划。 |
响应
成功的响应返回HTTP状态204(无内容)。
请求
| code language-shell |
|---|
|
| table 0-row-2 1-row-2 2-row-2 | |
|---|---|
| 属性 | 描述 |
path |
要更新的值的路径。 在这种情况下,由于您正在更新cron计划,因此需要将path的值设置为/schedule。 |
value |
cron计划的更新值。 该值需要采用cron计划的形式。 在此示例中,计划将在每月的第二日运行。 |
响应
成功的响应返回HTTP状态204(无内容)。
删除特定计划
您可以通过向/config/schedules端点发出DELETE请求并在请求路径中提供要删除的调度的ID,来请求删除特定调度。
API格式
DELETE /config/schedules/{SCHEDULE_ID}
{SCHEDULE_ID}id值。请求
| code language-shell |
|---|
|
响应
成功的响应返回HTTP状态204(无内容)。
将受众添加到计划 add-audiences
您可以通过向/config/schedules/add-audiences端点发出POST请求,将受众添加到特定计划。
API格式
POST /config/schedules/add-audiences
请求
| code language-shell |
|---|
|
idsegments响应
成功的响应返回HTTP状态200,其中包含操作的详细信息。
| code language-json |
|---|
|
| table 0-row-2 1-row-2 2-row-2 3-row-2 4-row-2 | |
|---|---|
| 属性 | 描述 |
added |
一个数组,其中包含已添加到计划的区段定义的ID。 |
existing |
一个数组,其中包含已列入计划的区段定义的ID。 |
invalid |
一个数组,其中包含属于请求正文一部分的无效区段定义ID。 |
segmentCount |
一个对象,其中包含以前属于计划一部分的区段定义数(previous)、现在属于计划一部分的区段定义数(current),以及这两个值之间的差异(diff)。 |
从计划中删除受众 remove-audiences
您可以通过向/config/schedules/remove-audiences端点发出POST请求,从特定计划中删除受众。
API格式
POST /config/schedules/remove-audiences
请求
| code language-shell |
|---|
|
idsegments响应
成功的响应返回HTTP状态200,其中包含操作的详细信息。
| code language-json |
|---|
|
| table 0-row-2 1-row-2 2-row-2 3-row-2 | |
|---|---|
| 属性 | 描述 |
removed |
一个数组,其中包含从计划中删除的区段定义ID。 |
notFound |
一个数组,其中包含未能在计划内找到的区段定义ID。 |
segmentCount |
一个对象,其中包含以前属于计划一部分的区段定义数(previous)、现在属于计划一部分的区段定义数(current),以及这两个值之间的差异(diff)。 |
获取受众地图 get-audience-map
您可以通过向/config/schedules/audience-map端点发出POST请求来获取受众的受众映射。 受众映射表示区段定义ID与这些ID所属计划之间的映射。
API格式
POST /config/schedules/audience-map
请求
| code language-shell |
|---|
|
segments响应
成功的响应返回HTTP状态200,其中包含有关受众和计划映射的详细信息。
| code language-json |
|---|
|
| table 0-row-2 1-row-2 2-row-2 | |
|---|---|
| 属性 | 描述 |
audienceMap |
区段定义ID与其所属计划的映射。 |
schedules |
一个对象,其中包含受众映射中列出的调度的相关信息。 |
触发计划作业 trigger
您可以通过向/config/schedules/trigger端点发出POST请求来手动触发要激活的计划。
API格式
POST /config/schedules/trigger
请求
| code language-shell |
|---|
|
id响应
成功的响应返回不含内容的HTTP状态200。
后续步骤
阅读本指南后,您现在可以更好地了解时间表的工作方式。
附录 appendix
以下附录说明了时间表中使用的cron表达式的格式。
格式
cron表达式是由6或7个字段组成的字符串。 该表达式将类似于以下内容:
0 0 12 * * ?
在cron表达式字符串中,第一个字段表示秒,第二个字段表示分钟,第三个字段表示小时,第四个字段表示一月中的第几天,第五个字段表示一月中的第几天,第六个字段表示一周中的第几天。 您还可以选择包含第七个字段,该字段表示年份。
, - * /, - * /, - * /, - * ? / L W, - * /, - * ? / L #, - * /SUN等同于使用sun。允许使用的特殊字符表示以下含义:
**置于小时字段意味着每 小时 次。?3,在周中的第几天字段中放置?。-9-15置于小时字段中,则意味着小时将包括9、10、11、12、13、14和15。,MON, FRI, SAT置于星期字段中,则意味着一周的日期包括星期一、星期五和星期六。//之前的值决定其增量位置,而放置在/之后的值决定其增量大小。 例如,如果将1/7放在分钟字段中,则意味着分钟将包括1、8、15、22、29、36、43、50和57。LLast,并且根据其使用的字段具有不同的含义。 如果将其与月中的日字段一起使用,则它表示月中的最后一天。 如果单独与星期字段一起使用,则它表示一周的最后一天,即星期六(SAT)。 如果将其与“星期”字段一起使用,并配合使用其他值,则它表示该月中该类型的最后一天。 例如,如果将5L放在星期字段中,则 仅 包含该月的最后一个星期五。W18W置于月份字段中,并且该月的18日是星期六,则会在17日的星期五触发,这是最接近的工作日。 如果当月18日是星期日,则会在19日星期一触发,这是最接近的工作日。 请注意,如果您将1W置于“月”字段中,且最近的工作日为上个月,则该事件仍将在 当前 月中最近的工作日触发。此外,您可以将
L和W结合使用,以生成LW,该日期将指定该月的最后一个工作日。##之前的值表示星期几,而放置在#之后的值表示当月它出现的次数。 例如,如果放入1#3,则事件将在月份的第三个星期日触发。 请注意,如果您输入X#5,而该月内没有出现该周的第5次发生次数,则事件将 不会 触发。 例如,如果放入1#5,并且该月没有第五个星期日,则事件将 不会 触发。示例
下表显示了cron表达式字符串示例及其含义。
0 0 13 * * ?0 30 9 * * ? 20220 * 18 * * ?0 0/10 17 * * ?0 13,38 5 ? 6 WED0 30 12 ? * 4#30 30 12 ? * 6L0 45 11 ? * MON-THU