Power AutomateWeb API

今後,所有流程都會儲存在 Common Data Service 中,並運用豐富的 Web API

本內容涵蓋的範圍為 Power Automate 解決方案 索引標籤中的流程管理。 目前,這些 API 不支援 我的流程 底下的流程。

撰寫 HTTP 要求

若要開始建立要求,您必須先建構 URL。 Power Automate Web API 的基底 URL 格式為:https://{Organization ID}.{Regional Subdomain}.dynamics.com/api/data/v9.1/。 這兩個參數為:

  • 組織識別碼,儲存流程的組織唯一名稱。

  • 區域子網域 取決於環境的位置。

若要取得這兩個參數:

  1. 前往 Power Platform 系統管理中心
  2. 選取您用來建置流程的環境。

流程 URL

  1. 複製環境 URL 中的組織識別碼和區域子網域。

流程 URL

您也可以透過線上管理 API 中的取得執行個體方法,以程式設計方式取得您可用的執行個體清單。

對 Web API 提出的每個要求都必須將 AcceptContent-type 標頭設為 application/json

最後,以 Azure AD 持有人權杖填入 Authorization 標頭。 您可以了解如何取得 Common Data Service 的 Azure AD 持有人權杖。 以此要求為例:

GET https://org00000000.crm0.dynamics.com/api/data/v9.1/workflows
Accept: application/json
Authorization: Bearer ey...

回應包含來自該環境中的流程清單:

{
    "@odata.context": "https://org00000000.crm0.dynamics.com/api/data/v9.1/$metadata#workflows",
    "value": [{
        "@odata.etag": "W/\"12116760\"",
        "category": 5,
        "statecode": 0,
        "workflowidunique": "00000000-0000-0000-0000-000000000001",
        "workflowid" : "00000000-0000-0000-0000-000000000002",
        "createdon": "2018-11-15T19:45:51Z",
        "_ownerid_value": "00000000-0000-0000-0000-000000000003",
        "modifiedon": "2018-11-15T19:45:51Z",
        "ismanaged": false,
        "name": "Sample flow",
        "_modifiedby_value": "00000000-0000-0000-0000-000000000003",
        "_createdby_value": "00000000-0000-0000-0000-000000000003",
        "type": 1,
        "description": "This flow updates some data in Common Data Service.",
        "clientdata": "{\"properties\":{\"connectionReferences\":{\"shared_commondataservice\":{\"source\":\"NotSpecified\",\"id\":\"/providers/Microsoft.PowerApps/apis/shared_commondataservice\",\"tier\":\"NotSpecified\"}},\"definition\":{...}},\"schemaVersion\":\"1.0.0.0\"}"
    }]
}

列出流程

如上所示,您可在 workflows 呼叫 GET 以取得工作流程清單。 每個工作流程各有多個屬性,但最相關的是:

屬性名稱 描述
類別 流程的類別。 不同的類型包括:0 - 傳統 Common Data Service 工作流程、1 - 傳統 Common Data Service 對話方塊、2 - 商務規則、3 - 傳統 Common Data Service 動作、4 - 商務程序流程及 5 - 自動、立即或排程的流程。
statecode 流程的狀態。 狀態可以是 0 - 關閉,或 1 - 開啟。
workflowuniqueid 這項流程安裝的唯一識別碼。
workflowid 雲端流程在所有匯入當中的唯一識別碼。
createdon 流程的建立日期。
_ownerid_value 擁有流程的使用者或團隊唯一識別碼。 這是來自 Common Data Service 中 systemusers 實體的識別碼。
modifiedon 流程上次更新的時間。
ismanaged 指出流程是否透過受控解決方案安裝。
名稱 您為流程指定的顯示名稱。
_modifiedby_value 最後更新流程的使用者。 這是來自 Common Data Service 中 systemusers 實體的識別碼。
_createdby_value 建立流程的使用者。 這是來自 Common Data Service 中 systemusers 實體的識別碼。
類型 指出流程執行的是流程,或是可用來建立額外流程的範本。 1 - 流程、2 - 啟用或 3 - 流程。
描述 使用者提供的流程描述。
clientdata 物件的強式編碼 JSON,該物件包含流程的 connectionReferences 及定義。

您也可以要求特定屬性、篩選流程清單,以及執行更多其他動作,如關於查詢資料的 Common Data Service API 文件中所述。 舉例來說,這個查詢只會傳回目前開啟的自動、立即或排程流程:

GET https://org00000000.crm0.dynamics.com/api/data/v9.1/workflows?$filter=category eq 5 and statecode eq 1
Accept: application/json
Authorization: Bearer ey...

建立雲端流程

workflows 集合上呼叫 POST 即可建立雲端流程。 自動、立即及排程流程的必要屬性有:category、name、type、primaryentity 及 clientdata。 對於這些類型的流程,請在 primaryentity 使用 none

您也可以提供 description 和 statecode。

POST https://org00000000.crm0.dynamics.com/api/data/v9.1/workflows
Accept: application/json
Authorization: Bearer ey...
Content-type: application/json
{
        "category": 5,
        "statecode": 0,
        "name": "Sample flow name",
        "type": 1,
        "description": "This flow reads some data from Common Data Service.",
        "primaryentity":"none",
        "clientdata": "{\"properties\":{\"connectionReferences\":{\"shared_commondataservice\":{\"connectionName\":\"shared-commondataser-00000000-0000-0000-0000-000000000004\",\"source\":\"Invoker\",\"id\":\"/providers/Microsoft.Power Apps/apis/shared_commondataservice\"}},\"definition\":{\"$schema\": \"https:\/\/schema.management.azure.com\/providers\/Microsoft.Logic\/schemas\/2016-06-01\/workflowdefinition.json#\",\"contentVersion\": \"1.0.0.0\",\"parameters\": {\"$connections\": {\"defaultValue\": {},\"type\": \"Object\"},\"$authentication\": {\"defaultValue\": {},\"type\": \"SecureObject\"}},\"triggers\": {\"Recurrence\": {\"recurrence\": {\"frequency\": \"Minute\",\"interval\": 1},\"type\": \"Recurrence\"}},\"actions\": {\"List_records\": {\"runAfter\": {},\"metadata\": {\"flowSystemMetadata\": {\"swaggerOperationId\": \"GetItems_V2\"}},\"type\": \"ApiConnection\",\"inputs\": {\"host\": {\"api\": {\"runtimeUrl\": \"https:\/\/firstrelease-001.azure-apim.net\/apim\/commondataservice\"},\"connection\": {\"name\": \"@parameters('$connections')['shared_commondataservice']['connectionId']\"}},\"method\": \"get\",\"path\": \"\/v2\/datasets\/@{encodeURIComponent(encodeURIComponent('default.cds'))}\/tables\/@{encodeURIComponent(encodeURIComponent('accounts'))}\/items\",\"queries\": {\"$top\": 1},\"authentication\": \"@parameters('$authentication')\"}}},\"outputs\": {}}},\"schemaVersion\":\"1.0.0.0\"}"
}

最重要的區段是 clientdata,其中包含流程所使用的 connectionReferences,以及流程的定義。 connectionReferences 是流程所使用的各連線對應。

屬性有三個:

屬性名稱 描述
connectionName 識別連線。 您可以前往 連線 頁面查看 connectionName,然後從連線 URL 加以複製。
來源媒體 EmbeddedInvokerInvoker 只對立即流程 (也就是使用者選取了按鈕以執行流程) 有效,並指出終端使用者會提供連線。 在這種情況下,就只會在設計階段用到 connectionName。 如果連線是 Embedded,表示會一律使用您指定的 connectionName。
識別碼 連接器的識別碼。 識別碼的開頭一律為 /providers/Microsoft.PowerApps/apis/,後面接著連接器名稱,您可從連線 URL 中複製該名稱,或從 連接器 頁面選取連接器來複製。

在執行 POST 要求後,您就會收到 OData-EntityId 標頭,其中會包含新流程的 workflowid

更新雲端流程

您可在工作流程呼叫 PATCH,以更新、開啟或關閉雲端流程。 使用 workflowid 屬性即可進行這些呼叫。 例如,您可以透過下列呼叫,更新流程的描述和擁有者:

PATCH https://org00000000.crm0.dynamics.com/api/data/v9.1/workflows(00000000-0000-0000-0000-000000000002)
Accept: application/json
Authorization: Bearer ey...
Content-type: application/json
{
    "description" : "This flow will ensure consistency across systems.",
    "ownerid@odata.bind": "systemusers(00000000-0000-0000-0000-000000000005)",
}

Note

用於變更擁有者的語法使用 odata.bind 格式。 這表示,您要將 @odata.bind 附加到屬性名稱,然後以 systemusers() 括住識別碼,而不是直接修補 _ownerid_value。

在另一個例子中,您可以透過這個呼叫來開啟雲端流程:

PATCH https://org00000000.crm0.dynamics.com/api/data/v9.1/workflows(00000000-0000-0000-0000-000000000002)
Accept: application/json
Authorization: Bearer ey...
Content-type: application/json
{
    "statecode" : 1
}

刪除雲端流程

使用簡單的 DELETE 呼叫即可刪除雲端流程:

DELETE https://org00000000.crm0.dynamics.com/api/data/v9.1/workflows(00000000-0000-0000-0000-000000000002)
Accept: application/json
Authorization: Bearer ey...

Note

您無法刪除已開啟的雲端流程。 必須先關閉流程 (請先參閱 更新雲端流程),否則會看到以下錯誤:Cannot delete an active workflow definition.

取得共用雲端流程的所有使用者

在 Common Data Service 中使用 函式 來列出具有存取權的使用者。 這個函式接受單一參數 Target:

GET https://org00000000.crm0.dynamics.com/api/data/v9.1/RetrieveSharedPrincipalsAndAccess(Target=@tid)?@tid={'@odata.id':'workflows(00000000-0000-0000-0000-000000000002)'}
Accept: application/json
Authorization: Bearer ey...

Target 參數是類似 JSON 的字串,具有單一屬性,稱為 @odata.id。 取代上方範例中的工作流程識別碼。 傳回的會是:

{
    "@odata.context": "https://org00000000.crm0.dynamics.com/api/data/v9.1/$metadata#Microsoft.Dynamics.CRM.RetrieveSharedPrincipalsAndAccessResponse",
    "PrincipalAccesses": [
        {
            "AccessMask": "ReadAccess",
            "Principal": {
                "@odata.type": "#Microsoft.Dynamics.CRM.systemuser",
                "ownerid": "00000000-0000-0000-0000-000000000005"
            }
        }
    ]
}

共用或取消共用雲端流程

您可以使用 GrantAccess 動作共用雲端流程。

POST https://org00000000.crm0.dynamics.com/api/data/v9.1/GrantAccess
Accept: application/json
Authorization: Bearer ey...
Content-type: application/json
{
    "Target" : {
        "@odata.type": "Microsoft.Dynamics.CRM.workflow",
        "workflowid" : "00000000-0000-0000-0000-000000000002"
    },
    "PrincipalAccess": {
        "Principal": {
            "@odata.type" : "Microsoft.Dynamics.CRM.systemuser",
            "ownerid" : "00000000-0000-0000-0000-000000000005"
        },
        "AccessMask": "ReadAccess"
    }
}

AccessMask 參數是一個對不同權限等級各有下列對應值的欄位:

姓名 描述
無​​ 無存取權。
ReadAccess 流程的讀取權限。
WriteAccess 流程的更新權限。
DeleteAccess 流程的刪除權限。
ShareAccess 流程的共用權限。
AssignAccess 流程擁有者的變更權限。

您可以用逗號合併權限;例如,傳遞 ReadAccess,WriteAccess 即可同時提供讀取和更新雲端流程的能力。

您可以透過 RevokeAccess 動作來 取消共用 雲端流程。 以下是範例:

POST https://org00000000.crm0.dynamics.com/api/data/v9.1/RevokeAccess
Accept: application/json
Authorization: Bearer ey...
Content-type: application/json
{
    "Target" : {
        "@odata.type": "Microsoft.Dynamics.CRM.workflow",
        "workflowid" : "00000000-0000-0000-0000-000000000002"
    },
    "Revokee": {
        "@odata.type" : "Microsoft.Dynamics.CRM.systemuser",
        "ownerid" : "00000000-0000-0000-0000-000000000005"
    }
}

RevokeAccess 會移除 AccessMask 中授與的所有權限。

匯出流程

使用 ExportSolution 動作可將流程匯出為 .zip 檔案。 首先將您想要的流程新增到解決方案

流程到了解決方案中,就可以呼叫下列動作:

POST https://org00000000.crm0.dynamics.com/api/data/v9.1/ExportSolution
Accept: application/json
Authorization: Bearer ey...
Content-type: application/json
{
    "SolutionName" : "Awesome solution 1",
    "Managed": false
}

ExportSolution 會在 ExportSoutionFile 屬性中傳回 base 64 編碼的字串。

{
    "@odata.context": "https://org00000000.crm0.dynamics.com/api/data/v9.1/$metadata#Microsoft.Dynamics.CRM.ExportSolutionResponse",
    "ExportSolutionFile": "UEsDBBQAAgAI..."
}

您接著可以將這個檔案儲存到原始檔控制中,及 (或) 使用您想用的任意版本管理或散發系統。

匯入流程

呼叫 ImportSolution 動作可匯入解決方案。

屬性名稱 描述
OverwriteUnmanagedCustomizations 如果 Common Data Service 中的流程已經有執行個體,則必須將此旗標設定為 true,才能將其匯入。 否則不會進行覆寫。
PublishWorkflows 指出傳統 Common Data Service 工作流程是否會在匯入時啟用。 這項設定不適用於其他類型的流程。
ImportJobId 提供唯一的新 GUID 以追蹤匯入作業。
CustomizationFile base 64 編碼的 zip 檔案,包含解決方案。
POST https://org00000000.crm0.dynamics.com/api/data/v9.1/ImportSolution
Accept: application/json
Authorization: Bearer ey...
Content-type: application/json
{
    "OverwriteUnmanagedCustomizations": false,
    "PublishWorkflows" : true,
    "ImportJobId" : "00000000-0000-0000-0000-000000000006",
    "CustomizationFile" : "UEsDBBQAAgAI..."
}

由於匯入是執行時間較長的作業,因此 ImportSolution 動作的回應會是 204 No content。 若要追蹤進度,請在 importjobs 物件呼叫 GET,並提供您包含在原始 ImportSolution 動作中的 ImportJobId

GET https://org00000000.crm0.dynamics.com/api/data/v9.1/importjobs(00000000-0000-0000-0000-000000000006)
Accept: application/json
Authorization: Bearer ey...

此呼叫會傳回匯入作業的狀態,包括 progress (完成百分比)、startedoncompletedon (若匯入已完成)。

在匯入成功完成後,由於 connectionNames 在目的地環境中可能會不同 (若連線已存在),您必須為流程設定連接器。 如果您要在目的地環境中設定新的連線,流程擁有者就必須在 Power Automate 設計工具中加以建立。 如果連線已在新環境中設定,您就可以使用連線的名稱來 PATCH 流程的 clientData

Note

是否能請您告知您偏好的慣用文件語言? 請填寫問卷。 (請注意,本問卷為英文版)

完成問卷大約需要七分鐘。 本問卷將不會收集個人資料 (隱私權聲明)。