使用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端點
建立套件
此呼叫會執行多步驟流程。
第一個步驟會建立狀態為「組裝」的空白促銷活動套件。
第二個步驟使用POST本文中提供的objectCollections
陣列來組合來自Workfront的請求記錄。 視要求的記錄數和Workfront設定而定,此步驟可能需要幾分鐘的時間才能完成。 此程式結束時,空白的促銷活動套件會以packageEntities
更新,而狀態會自動設為「草稿」。
objectCollections
陣列的結構。objCode
金鑰。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內文中提供的促銷活動套件的任何內容。
可編輯的屬性包括:
- 名稱(字串)
- 說明(字串)
- 狀態(含值驗證的字串)
如需可用狀態的詳細說明,請參閱文章在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
。 允許UPDATE 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