Power Automate Web API

[アーティクル]
03/11/2022

今後、すべてのフローは Dataverse に格納され、豊富な Web API を利用します。

このコンテンツでは、Power Automate の ソリューション タブに含まれるフローの管理について説明しています。現在、マイフロー のフローはこのような API ではサポートされていません。

HTTP 要求を作成する

要求の作成を始めるには、まず URL を構築する必要があります。 Power Automate Web API のベース URL の形式は https://{Organization ID}.{Regional Subdomain}.dynamics.com/api/data/v9.1/ です。次の 2 つのパラメーターがあります。

組織 ID は、フローを格納する環境の一意の名前です。
リージョンサブのドメイン は、環境の場所によって変わります。

これらの2つのパラメーターを取得する方法。

Power Platform 管理センターに移動します。
フローの構築に使用する環境を選択します。

ご利用のフローの環境

環境の URL から組織の ID と地域のサブドメインをコピーします。

組織の ID とリージョン。

オンラインマネジメント API のインスタンスの取得メソッドを使用して、利用可能なインスタンスの一覧をプログラムで取得することも可能です。

Web API に対する各要求で、Accept と Content-type ヘッダーを application/json に設定する必要があります。

最後に、Authorization ヘッダーに Azure AD ベアラートークンを設定します。 Dataverse の 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 Dataverse.",
        "clientdata": "{\"properties\":{\"connectionReferences\":{\"shared_commondataservice\":{\"source\":\"NotSpecified\",\"id\":\"/providers/Microsoft.PowerApps/apis/shared_commondataservice\",\"tier\":\"NotSpecified\"}},\"definition\":{...}},\"schemaVersion\":\"1.0.0.0\"}"
    }]
}

フローの一覧表示

前述のように、workflows に対して GET を呼び出すことでワークフローの一覧を取得できます。各ワークフローには多くのプロパティがありますが、関連性の高いものは次のとおりです。

プロパティ名	内容
category	フローのカテゴリ。さまざまなカテゴリがあります。 0 - クラシック Dataverse ワークフロー。 1 - クラシック Dataverse ダイアログ。 2 - ビジネスルール。 3 - クラシック Dataverse アクション。 4 - ビジネスプロセスフロー。 5 - 自動化フロー、インスタントフロー、予定フロー。 6 - Desktop フロー。
statecode	フローの状態。状態は 0 がオフ、または 1 がオンです。
workflowidunique	フローのこのインストールの一意識別子。
workflowid	すべてのインポート全体でのクラウドフローの一意識別子。
createdon	フローが作成された日付。
_ownerid_value	フローを所有するユーザーまたはチームの一意識別子。これは、Dataverse の systemusers テーブルの ID です。
modifiedon	フローの最終更新日時。
ismanaged	フローが管理ソリューションを介してインストールされたかどうかを示します。
name	フローに付けた表示名。
_modifiedby_value	フローを最後に更新したユーザー。これは、Dataverse の systemusers テーブルの ID です。
_createdby_value	フローを作成したユーザー。これは、Dataverse の systemusers テーブルの ID です。
type	フローが実行中のフローか、追加のフローを作成するために使用できるテンプレートかを示します。 1 - フロー、2 - アクティブ化、または 3 - テンプレート。
description	ユーザーが指定したフローの説明。
clientdata	connectionReferences とフローの定義を含むオブジェクトの文字列エンコードされた JSON。

Dataverse ワークフローのドキュメントには、プロパティ/フィールドとその使用法に関する追加情報があります。

また、データのクエリを実行するための Dataverse 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 Dataverse.",
        "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\"}"
}

最も重要なセクションは、フローが使用する connectionReferences が含まれている clientdata と、フローの定義です。 connectionReferences は、フローが使用する各接続へのマッピングです。

次の 3 つのプロパティがあります。

プロパティ名	内容
connectionName	接続を特定します。接続ページに移動し、接続の URL からコピーすることで、connectionName を確認することができます。
source	`Embedded` または `Invoker` のいずれかです。 `Invoker` はインスタントフロー (ユーザーがボタンを選択してフローを実行したフロー) の場合にのみ有効であり、エンドユーザーが接続を提供することを示します。この場合、connectionName は設計時にのみ使用されます。接続が `Embedded` の場合は、指定した connectionName が常に使用されることを意味します。
id	コネクタの識別子。 ID は常に `/providers/Microsoft.PowerApps/apis/` で始まり、次にコネクタ名が含まれます。これは、接続の URL からコピーするか、コネクタページからコネクタを選択してコピーして取得できます。

POST 要求を実行すると、新しいフローの workflowid を含む OData-EntityId ヘッダーを受け取ります。

クラウドフローを更新

ワークフローで 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 形式を使用します。つまり、_ownerid_value フィールドに直接パッチを適用する代わりに、@odata.bind をプロパティ名に追加してから systemusers() を使用して ID をラップします。

もう 1 つの例を挙げると、次の呼び出しを使用してクラウドフローを有効にすることができます。

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. が表示されます。

クラウドフローが共有されているすべてのユーザーを取得する

アクセス権を持つユーザーを一覧表示するには、Dataverse の関数を使用します。この関数は、Target の 1 つのパラメーターを受け取ります。

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 パラメーターは、@odata.id という単一のプロパティを持つ JSON のような文字列です。前述の例のワークフロー 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 パラメーターは、さまざまなアクセス許可レベルに対して次の値を持つフィールドです。

件名	内容
None	アクセス権がありません。
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 で付与されているすべてのアクセス許可が削除されます。

フローをエクスポートする

フローを .zip ファイルにエクスポートするには、ExportSolution アクションを使用します。まず、目的のフローをソリューションに追加します。

ソリューションにフローが追加されたら、次のアクションを呼び出します。

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 を使用すると、base 64 でエンコードされた文字列が ExportSoutionFile プロパティで返されます。

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

このファイルをソース管理に保存したり、必要なバージョン管理や配布システムを使用したりすることができます。

フローをインポートする

ソリューションをインポートするには、ImportSolution アクションを呼び出します。

プロパティ名	内容
OverwriteUnmanagedCustomizations	Dataverse にこのようなフローの既存のインスタンスがある場合、インポートするには、このフラグを `true` に設定する必要があります。それ以外の場合は上書きされません。
PublishWorkflows	インポート時にクラシック Dataverse ワークフローをアクティブ化するかどうかを示します。この設定は他の種類のフローには適用されません。
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 (完了 %)、startedon、completedon (インポートが完了した場合) などのインポート操作の状態が返されます。

インポートが正常に完了したら、connectionNames は (仮に接続が存在する場合) 対象の環境で異なる可能性があるため、フローの接続を設定する必要があります。対象の環境で新しい接続を設定する場合は、フローの所有者がそれらを Power Automate Designer で作成する必要があります。新しい環境で接続が既に設定されている場合は、接続の名前を使用してフローの clientData に対する PATCH を実行できます。

Note

ドキュメントの言語設定についてお聞かせください。簡単な調査を行います。 (この調査は英語です)

この調査には約 7 分かかります。個人データは収集されません (プライバシーステートメント)。

Power Automate Web API

HTTP 要求を作成する

フローの一覧表示

クラウド フローを作成

クラウド フローを更新

クラウド フローを削除

クラウド フローが共有されているすべてのユーザーを取得する

クラウド フローの共有または共有解除

フローをエクスポートする

フローをインポートする

フィードバック

クラウドフローを作成

クラウドフローを更新

クラウドフローを削除

クラウドフローが共有されているすべてのユーザーを取得する

クラウドフローの共有または共有解除