使用Workfront环境升级API在Workfront环境之间移动对象
“环境升级”功能允许您将与配置相关的对象从一个环境移动到另一个环境。 您可以使用Workfront API移动这些对象,如本文所述。
有关使用Workfront应用程序在环境之间移动对象的说明,请参阅:
访问要求
您必须具备以下条件:
有关此表中信息的更多详细信息,请参阅Workfront文档中的访问要求。
先决条件
创建升级包端点假定您已配置源环境。 此API调用需要手动创建Workfront对象代码和对象GUID的对象映射。 此地图的特定结构如下所述。
环境升级支持的对象
环境升级功能旨在提供与配置相关的对象从一个环境移动到另一个环境的功能。 它不支持移动事务性对象的功能(只有有限的例外)。
有关可升级对象及其包含的可升级子对象的列表,请参阅在Workfront环境之间移动对象概述一文中的环境升级支持的对象。
身份验证
API对每个请求进行身份验证,以确保客户端有权查看或修改请求的对象。
身份验证是通过传入会话ID或API密钥执行的,可使用以下方法提供该密钥:
请求标头身份验证
首选的身份验证方法是传递包含会话令牌的名为SessionID的请求标头。 这样可以安全地抵御跨站点请求伪造(CSRF)攻击,并且不会出于缓存目的干扰URI。
以下是请求标头的示例:
GET /attask/api/v15.0/project/search
SessionID: abc1234
API端点
创建资源包
此调用执行多步骤流程。
第一步会创建一个处于“ASSEMBLING”状态的空促销包。
第二步使用POST正文中提供的objectCollections
数组从Workfront汇编所请求的记录。 完成此步骤可能需要几分钟,具体取决于请求的记录数以及Workfront配置。 在此流程结束时,空的促销活动包将使用packageEntities
进行更新,并且状态会自动设置为“草稿”。
objectCollections
数组的结构。objCode
密钥,该密钥与Workfront API资源管理器中记录的对象代码相对应。entities
集合。 这需要ID
字段。 它还可以接受可选的name
特性,以便于了解ID
表示的内容。objectCollections
列表中请求的允许对象代码的列表,请参阅本文中的环境升级支持的对象部分。URL
POST https://{domain}.{environment}.workfront.com/environment-promotion/api/v1/packages
标头
{
"apikey": "**********",
"Content-Type": "application/json"
}
或
{
"sessionID": "*****************",
"Content-Type": "application/json"
}
正文
{
"name": "Agency Onboarding - 2023-06-06",
"description": "This promotion package contains configuration to support the agency onboarding processes...",
"source": "https://{domain}.{environment}.workfront.com",
"objectCollections": [
{
"objCode": "PROJ",
"entities": [
{
"ID": "6419b8b9001151ee258921a4f7597ba1",
"name": "Agency Request"
}
]
},
{
"objCode": "TMPL",
"entities": [
{
"ID": "6419b8b9001151ee258921a4f7597bb2",
"name": "New Agency Onboarding"
},
{
"ID": "6419b8b9001151ee258921a4f7597bc3",
"name": "New Agency Offboarding"
}
]
},
{
"objCode": "PTLTAB",
"entities": [
{
"ID": "645e6435000b4aaebe4776f4a42ed5ad",
"name": "Agency Performance and Readiness"
}
]
}
]
}
响应
200
{
"data": {
"id": "1d5693b9-b7b5-492d-8219-c21f34bcaca6",
"name": "Agency Onboarding - 2023-06-06",
"description": "This promotion package contains configuration to support the agency onboarding processes...",
"source": "https://{domain}.{environment}.workfront.com",
"status": "ASSEMBLING",
"version": 1,
"createdAt": "2023-06-06T17:29:21.600Z",
"createdById": "61aa9d0e0005fcee8f212835bdaa2619",
"publishedAt": null,
"customerId": "61aa9d090005fa42152c1cb66659f38d"
}
}
获取程序包列表
此调用会返回属于客户的未过滤促销包列表。
响应将包括从客户的任何沙盒、预览或Workfront的生产实例创建的所有包。
URL
GET https://{domain}.{environment}.workfront.com/environment-promotion/api/v1/packages
标头
{
"apikey": "**********"
}
或
{
"sessionID": "*****************"
}
正文
空
响应
200
{
"data": [
{
"id": "1d5693b9-b7b5-492d-8219-c21f34bcaca6",
"name": "Agency Onboarding - 2023-06-06",
"description": "This promotion package contains configuration to support the agency onboarding processes...",
"status": "ASSEMBLING",
"createdAt": "2023-06-06T17:29:21.600Z",
"deletedAt": null
},
{...}
]
}
<! — 检查上面的“状态” — 它是否已添加?—>
按ID获取包
此调用返回所请求促销活动包的详细信息。
无论升级包的原始来源如何,均可通过任何环境发出请求。
URL
GET https://{domain}.{environment}.workfront.com/environment-promotion/api/v1/packages/{id}
标头
{
"apikey": "**********"
}
或
{
"sessionID": "*****************"
}
正文
空
响应
200
{
"data": {
"id": "1d5693b9-b7b5-492d-8219-c21f34bcaca6",
"name": "Agency Onboarding - 2023-06-06",
"description": "This promotion package contains configuration to support the agency onboarding processes...",
"source": "https://{domain}.{environment}.workfront.com",
"status": "DRAFT",
"version": 1,
"createdAt": "2023-06-06T17:29:21.600Z",
"publishedAt": null,
"customerId": "61aa9d090005fa42152c1cb66659f38d",
"packageEntities": {
"GROUP": [
{
"id": "52aa9d0e0005fcee8f212835bdaa2691",
"name": "Default Group",
"description": "null"
- or -
"description": "..."
}
],
"ROLE": [
{...}
],
...
}
}
}
更新包的特定属性
此调用会更新促销活动正文中提供的促销PATCH包的任何内容。
可编辑的属性包括:
- 名称(字符串)
- description(字符串)
- 状态(带值验证的字符串)
有关可用状态的详细说明,请参阅在Workfront环境之间移动对象概述一文中的环境升级状态。
URL
PATCH https://{domain}.{environment}.workfront.com/environment-promotion/api/v1/packages/{id}
标头
{
"apikey": "**********",
"Content-Type": "application/json"
}
或
{
"sessionID": "*****************",
"Content-Type": "application/json"
}
正文
{
"status": "ACTIVE"
}
响应
200
{
"data": {
"id": "1d5693b9-b7b5-492d-8219-c21f34bcaca6",
"name": "Agency Onboarding - 2023-06-06",
"description": "This promotion package contains configuration to support the agency onboarding processes...",
"source": "https://{domain}.{environment}.workfront.com",
"status": "ACTIVE",
"version": 1,
"createdAt": "2023-06-06T17:29:21.600Z",
"publishedAt": "2023-06-06T19:39:01.600Z",
"customerId": "61aa9d090005fa42152c1cb66659f38d",
"packageEntities": {
"GROUP": [
{
"id": "52aa9d0e0005fcee8f212835bdaa2691",
"name": "Default Group",
"description": "..."
}
],
"ROLE": [
{...}
],
...
}
}
}
删除资源包
此调用将删除促销包记录。 此操作不可逆。
URL
DELETE https://{domain}.{environment}.workfront.com/environment-promotion/api/v1/packages/{id}
标头
{
"apikey": "**********"
}
或
{
"sessionID": "*****************"
}
正文
空
响应
200
Deleted
执行预运行
此调用会对包定义与URL中标识的目标环境进行比较。
结果是一个JSON主体,用于标识是否在目标环境中找到升级对象。
对于每个升级对象,将设置以下actions
之一:
此服务的Alpha功能当前不支持UPDATE action
。 允许更新action
的选项是我们正在研究的内容。
URL
POST https://{domain}.{environment}.workfront.com/environment-promotion/api/v1/packages/:id/prepare-installation
标头
{
"apikey": "**********",
"Content-Type": "application/json"
}
或
{
"sessionID": "*****************",
"Content-Type": "application/json"
}
正文
{}
响应
200
{
"environmentPromotionPackageId": "45f2ae94-76c0-4b13-8f3b-f688de83043d",
"environmentPromotionPackageVersion": 1,
"id": "c0bc79bd-c9c1-4b5b-b118-b1241392de0e",
"userId": "5ba38da500b752fd66439d4f6a9999a1",
"customerId": "5ba38d9d00b74f0c7a38b1b487fc9710",
"status": "PREPARING",
"environment": "mmi.my.workfront.com",
"registeredAt": "2023-10-19T20:00:16.697Z",
"updatedAt": "2023-10-19T20:00:16.701Z",
"translationMap": {
"CTGY": {
"62d9c9a0000013aeeefe7242a0a5fdb2": {
"name": "Example Document Form",
"action": "USEEXISTING",
"isValid": true,
"targetId": "62d9c9a0000013aeeefe7242a0a5fdb2"
}
},
"PGRP": {
"62d1eee4001c6618e6b9f9a588ba1598": {
"name": "Asset Detail",
"action": "USEEXISTING",
"isValid": true,
"targetId": "62d1eee4001c6618e6b9f9a588ba1598"
}
},
"GROUP": {
"5ba38da500b752b0f46d13186030b7ad": {
"name": "Default Group",
"action": "USEEXISTING",
"isValid": true,
"targetId": "5ba38da500b752b0f46d13186030b7ad"
}
},
"PARAM": {
"62d1eee400f8578895166ee91a83f97a": {
"name": "Asset Type",
"action": "USEEXISTING",
"isValid": true,
"targetId": "62d1eee400f8578895166ee91a83f97a"
},
"62d1eee50001407c713514a8970b58e4": {
"name": "Keywords",
"action": "USEEXISTING",
"isValid": true,
"targetId": "62d1eee50001407c713514a8970b58e4"
},
"62d1eee5000333ac3981ea4f3df6d88e": {
"name": "Permitted Uses",
"action": "USEEXISTING",
"isValid": true,
"targetId": "62d1eee5000333ac3981ea4f3df6d88e"
},
"62d1eee5000b188e9ec8039a097fc7ab": {
"name": "File Format",
"action": "USEEXISTING",
"isValid": true,
"targetId": "62d1eee5000b188e9ec8039a097fc7ab"
},
"62d1eee500100c159fd5f838ce560507": {
"name": "CTA",
"action": "USEEXISTING",
"isValid": true,
"targetId": "62d1eee500100c159fd5f838ce560507"
},
"62d9c988001c1f23954dbb9d646335b5": {
"name": "Other CTA",
"action": "USEEXISTING",
"isValid": true,
"targetId": "62d9c988001c1f23954dbb9d646335b5"
},
"62d9c9880070f546cf4c798ea6c3eaa4": {
"name": "Other Audience",
"action": "USEEXISTING",
"isValid": true,
"targetId": "62d9c9880070f546cf4c798ea6c3eaa4"
},
"62d9c990006258baf1b40f2569c3eab7": {
"name": "Target Audience",
"action": "USEEXISTING",
"isValid": true,
"targetId": "62d9c990006258baf1b40f2569c3eab7"
}
}
}
}
id
字段。 在此示例中,id
字段是自顶向下第三的,其值以c0bc79bd
开头。执行安装
此调用将尝试将升级包安装到POSTURL中标识的目标环境中。
URL
POST https://{domain}.{environment}.workfront.com/environment-promotion/api/v1/installations/{id}/install
标头
{
"apikey": "**********",
"Content-Type": "application/json"
}
或
{
"sessionID": "*****************",
"Content-Type": "application/json"
}
正文
{
}
响应
202
{}
获取特定软件包的安装列表
结果包括已部署该包的所有环境中的安装事件。 它们不限于发出请求的环境的安装。 这允许您识别哪些环境已收到此包。
URL
GET https://{domain}.{environment}.workfront.com/environment-promotion/api/v1/installations?environmentPromotionPackageId={environmentPromotionPackageId}
标头
{
"apikey": "**********"
}
或
{
"sessionID": "*****************"
}
正文
空
响应
200
[
{
"id": "2892b936-e09e-455a-935f-e1462ab9753c",
"environmentPromotionPackageId": "4fae2b9d-d315-45f4-909f-a0c0d79fc65d",
"environmentPromotionPackageVersion": 1,
"userId": "8fbbc5bcf4f94a5b862483ee05573e73",
"customerId": "54286d78b064451096752b99bf968481",
"status": "INSTALLED",
"environment": "https://{domain}.{environment}.workfront.com",
"registeredAt": "2021-03-16T02:21:31.908Z",
"updatedAt": null,
"translationMap": {
"ROLE": {
"5f6d114f006883209828ddd9088e63b3": {
"name": "DAM Curator",
"action": "USEEXISTING",
"isValid": true,
"targetId": "600f4bed00028a718599f29575840053"
},
"ad535a9ebe647361e053a7656a0a1575": {
"name": "Copywriter",
"action": "USEEXISTING",
"isValid": true,
"targetId": "600f162700001ca051081c06667b14a4"
},
...
},
"TMPL": {
"5f9b317c00b3db5af69abcd1ed5f82aa": {
"name": "Digital Asset Production (Integrated)",
"action": "CREATE",
"isValid": true,
"targetId": "6054cda40000d5af63dc811d9c2b3a07"
},
...
},
...
}
},
{...}
]
获取安装的安装详细信息
此调用将返回安装服务为特定安装生成的最终translationMap
。
每个记录将说明规定的action
是什么,以及该操作是否成功。
对于具有CREATE action
的记录,targetId
字段将设置为目标系统中新创建记录的值。 此外,installationStatus
字段将设置为INSTALLED。
对于具有USEEXISTING action
的记录,还将设置targetId
字段,installationStatus
字段将设置为REGISTERED。 这表示映射过程已完成,并且安装服务确认已评估记录,并且没有要执行的任何操作。
如果记录具有CREATE action
,但无法成功创建记录,则installationStatus
将设置为FAILED,并且还会提供失败的原因。
URL
GET https://{domain}.{environment}.workfront.com/environment-promotion/api/v1/installations/{id}
标头
{
"apikey": "**********"
}
或
{
"sessionID": "*****************"
}
正文
空
响应
200
{
"id": "2892b936-e09e-455a-935f-e1462ab9753c",
"environmentPromotionPackageId": "4fae2b9d-d315-45f4-909f-a0c0d79fc65d",
"environmentPromotionPackageVersion": 1,
"userId": "8fbbc5bcf4f94a5b862483ee05573e73",
"customerId": "54286d78b064451096752b99bf968481",
"status": "INSTALLED",
"environment": "https://{domain}.{environment}.workfront.com",
"registeredAt": "2021-03-16T02:21:31.908Z",
"updatedAt": null,
"translationMap": {
"ROLE": {
"5f6d114f006883209828ddd9088e63b3": {
"name": "DAM Curator",
"action": "USEEXISTING",
"isValid": true,
"targetId": "600f4bed00028a718599f29575840053"
},
...
},
"TMPL": {
"5f9b317c00b3db5af69abcd1ed5f82aa": {
"name": "Digital Asset Production (Integrated)",
"action": "CREATE",
"isValid": true,
"targetId": "6054cda40000d5af63dc811d9c2b3a07"
},
...
},
...
}
}
覆盖
这是一个三步过程。
- 创建翻译映射(这类似于“准备安装”阶段)
- 编辑生成的翻译映射,为要覆盖的任何对象设置
action
和targetId
字段。 操作应为OVERWRITING
,targetId
应为应覆盖的对象的uuid - 执行安装。
步骤1 — 创建翻译图
URL
POST https://{domain}.{environment}.workfront.com/environment-promotion/api/v1/packages/{id}/translation-map
正文
无
响应
具有202 - OK
状态的翻译映射
{
{objcode}: {
{object uuid}: {
"targetId": {uuid of object in destination},
"action": {installation action},
"name": {name of the object},
"isValid": true
},
{...more objects}
},
{...more objcodes}
}
示例
{
"UIVW": {
"109f611680bb3a2b0c0a8c1f5ec63f6d": {
"targetId": "6643a26b0001401ff797ccb318f97aa6",
"action": "CREATE",
"name": "Actual Portfolio Cost by Program",
"isValid": true
}
},
"UIGB": {
"edb4c6c127d38910e4860eb25569a5cc": {
"targetId": "6643a26b000178fb5cc27b74cc1e87ec",
"action": "USEEXISTING",
"name": "Actual Portfolio Cost by Program",
"isValid": true
}
},
"UIFT": {
"f97b662e229fd09ee595d8d359ec88bd": {
"targetId": "6643a26b00015cdd6727b76d6fda1d1d",
"action": "USEEXISTING",
"name": "Actual Portfolio Cost by Program",
"isValid": true
}
},
"PTLSEC": {
"4bb80aa88a96420296a7f47bf866f162": {
"targetId": "4bb80aa88a96420296a7f47bf866f162",
"action": "USEEXISTING",
"name": "Actual Portfolio Cost by Program",
"isValid": true
}
},
"EXTSEC": {
"65f8637900015e4dceb6fe079bd5409d": {
"targetId": "65f8637900015e4dceb6fe079bd5409d",
"action": "USEEXISTING",
"name": "Asnyc List",
"isValid": true
}
},
"PTLTAB": {
"65f8638a00016422a83ddc3508852d0f": {
"targetId": "65f8638a00016422a83ddc3508852d0f",
"action": "CREATEWITHALTNAME",
"name": "Cool 2.0 The Best",
"isValid": true
}
}
}
步骤2 — 修改翻译图
此步骤没有端点。
-
在第1步 — 创建翻译映射中返回的翻译映射中,检查将安装的对象列表。
-
将每个对象上的操作字段更新为所需的安装操作。
-
验证每个对象上的
targetId
。 如果设置操作是USEEXISTING
或OVERWRITING
,则应将targetId
设置为目标环境中目标对象的UUID。 对于任何其他操作,targetId都应为空字符串。note note NOTE 如果检测到冲突,则已填充 targetId
。
步骤3 — 安装
URL
POST https://{domain}.{environment}.workfront.com/environment-promotion/api/v1/packages/{id}/install
正文
这是一个具有单个字段translationMap
的对象,该字段应等于步骤2 — 修改翻译映射中的修改翻译映射。
{
"translationMap": {
{objcode}: {
{object uuid}: {
"targetId": {uuid of object in destination},
"action": {installation action},
"name": {name of the object},
"isValid": true
},
{...more objects}
},
{...more objcodes}
}
}
示例
{
"translationMap": {
"UIVW": {
"109f611680bb3a2b0c0a8c1f5ec63f6d": {
"targetId": "6643a26b0001401ff797ccb318f97aa6",
"action": "USEEXISTING",
"name": "Actual Portfolio Cost by Program",
"isValid": true
}
},
"UIGB": {
"edb4c6c127d38910e4860eb25569a5cc": {
"targetId": "6643a26b000178fb5cc27b74cc1e87ec",
"action": "USEEXISTING",
"name": "Actual Portfolio Cost by Program",
"isValid": true
}
},
"UIFT": {
"f97b662e229fd09ee595d8d359ec88bd": {
"targetId": "6643a26b00015cdd6727b76d6fda1d1d",
"action": "OVERWRITING",
"name": "Actual Portfolio Cost by Program",
"isValid": true
}
},
"PTLSEC": {
"4bb80aa88a96420296a7f47bf866f162": {
"targetId": "4bb80aa88a96420296a7f47bf866f162",
"action": "USEEXISTING",
"name": "Actual Portfolio Cost by Program",
"isValid": true
}
},
"EXTSEC": {
"65f8637900015e4dceb6fe079bd5409d": {
"targetId": "65f8637900015e4dceb6fe079bd5409d",
"action": "USEEXISTING",
"name": "Asnyc List",
"isValid": true
}
},
"PTLTAB": {
"65f8638a00016422a83ddc3508852d0f": {
"targetId": "65f8638a00016422a83ddc3508852d0f",
"action": "CREATEWITHALTNAME",
"name": "Cool 2.0 The Best",
"isValid": true
}
}
}
}
响应
响应包括{uuid of the created installation}
和202 - ACCEPTED
状态。
示例: b6aa0af8-3520-4b25-aca3-86793dff44a6