コードを使ったデスクトップフローでの作業

開発者は、デスクトップフローのトリガーやキャンセルのプログラム化など、デスクトップフローの機能をアプリケーションに追加することができます。 Microsoft Dataverse プラットフォームには、これらの機能が用意されています。

前提条件

Dataverse Web API、Dataverse での認証、および Dataverse での OAuth の使用に関する知識。
Dataverse 環境と組織の概念、および組織の URL を手動またはプログラムで取得する方法に関する知識。
デスクトップフローの概念と接続とは何か、および接続を作成する方法に関する知識。

重要

この記事では、URL 内のすべての角かっこ [...] と入力/出力データを、実際のシナリオに固有の値に置き換えます。

利用可能なデスクトップフローの一覧表示

Dataverse では、すべてのデスクトップフロースクリプトがワークフローエンティティの一部として格納されます。

デスクトップフローを識別するために、カテゴリに基づいてワークフローのリストをフィルタリングします。

デスクトップフローの取得要求

Authorization: Bearer eyJ0eXAiOi...
Accept: application/json

GET https://[Organization URI]/api/data/v9.2/workflows?$filter=category+eq+6&$select=name,workflowid&$orderby=name HTTP/1.1

注記

既定では、この要求は発行されたデスクトップフローのみを返します。未発行 (下書き) のデスクトップフローを応答に含めるには、値がtrueMSCRM.IncludeUnpublished要求ヘッダーを追加します。

発行されていない (下書き) フローを含むデスクトップフローを取得する要求

Authorization: Bearer eyJ0eXAiOi...
Accept: application/json
MSCRM.IncludeUnpublished: true

GET https://[Organization URI]/api/data/v9.2/workflows?$filter=category+eq+6&$select=name,workflowid&$orderby=name HTTP/1.1

デスクトップフローを取得リクエストへの応答

{
    "@odata.context": "https://[Organization URI]/api/data/v9.2/$metadata#workflows(name,workflowid)",
    "value": [
        {
            "@odata.etag": "W1069462",
            "name": "Desktop flow 1",
            "workflowid": "f091ffab-58bb-4630-a115-659453d56f59",
        },
        {
            "@odata.etag": "W1028555",
            "name": "Desktop flow 2",
            "workflowid": "eafba1a2-e8d4-4efa-b549-11d4dfd9a3d1",
        }
    ]
}

デスクトップフローのスキーマを取得する

入力または出力のフロースキーマを取得する必要がある場合は、ターゲットワークフローの clientData フィールドを使用します。

デスクトップフローの入力スキーマを要求する

Authorization: Bearer eyJ0eXAiOi...
Accept: application/json

GET https://[Organization URI]/api/data/v9.2/workflows([Workflow Id])/inputs/$value HTTP/1.1

デスクトップフローの入力スキーマの取得要求に対する応答

{
    "schema": {
        "properties": {
            "inputText": {
                "default": "",
                "description": "",
                "format": null,
                "title": "inputText",
                "type": "string",
                "value": ""
            },
            "inputInteger": {
                "default": "",
                "description": "",
                "format": null,
                "title": "inputInteger",
                "type": "number",
                "value": "0"
            }
        },
        "type": "object"
    }
}

デスクトップフローの出力スキーマを要求する

Authorization: Bearer eyJ0eXAiOi...
Accept: application/json

GET https://[Organization URI]/api/data/v9.2/workflows([Workflow Id])/outputs/$value HTTP/1.1

デスクトップフローの出力スキーマの取得要求に対する応答

{
    "schema": {
        "properties": {
            "outputText": {
                "default": "",
                "description": "",
                "format": null,
                "title": "outputText",
                "type": "string",
                "value": null
            },
            "outputInteger": {
                "default": "",
                "description": "",
                "format": null,
                "title": "outputInteger",
                "type": "number",
                "value": null
            }
        },
        "type": "object"
    }
}

デスクトップフローの実行状況を取得する

Dataverse は、すべてのデスクトップフロー実行を flowsession エンティティに格納します。

デスクトップフローの実行状況を要求する

Authorization: Bearer eyJ0eXAiOi...
Accept: application/json

GET https://[Organization URI]/api/data/v9.2/flowsessions([Flow session ID])?$select=statuscode,statecode,startedon,completedon HTTP/1.1

デスクトップフローの実行状況に対する応答

{
    "@odata.context": "https://[Organization URI]/api/data/v9.2/$metadata#flowsessions(statuscode,statecode,startedon,completedon)/$entity",
    "@odata.etag": "W1276122",
    "statuscode": 8,
    "statecode": 0,
    "startedon": "2022-06-16T12:54:40Z",
    "completedon": "2022-06-16T12:57:46Z",
}

デスクトップフロー出力の取得

デスクトップフローに出力がある場合は、 outputs フィールドにクエリを実行して取得します。

デスクトップフロー出力要求

Authorization: Bearer eyJ0eXAiOi...
Accept: application/json

GET https://[Organization URI]/api/data/v9.2/flowsessions([Flow session ID])/outputs/$value HTTP/1.1

デスクトップフロー出力に関する要望への対応

{
    "Output1": "My output value"
}

デスクトップフローの実行をトリガーする

Dataverse を使用することで、アプリケーションを通じてデスクトップフローをトリガーする機能を追加することができます。この機能を実装するには、 RunDesktopFlow アクションを使用します。

アクションを呼び出すには、次の情報が必要です。

実行したいデスクトップフローのID。この記事で前述した「使用可能なデスクトップフローの一覧表示」セクションで説明されているように、API を使用してこの ID を取得します。

ヒント

または、Power Automateのデスクトップフローの詳細 URL から手動で ID を取得します。 URL の形式は https://make.powerautomate.com/manage/environments/[Environment ID]/uiflows/[Desktop Flow ID]/details です。

詳細については、デスクトップフローを管理するを参照します。
デスクトップフロー接続 (マシンまたはマシングループを対象とする) のname。これはフローの実行に使用されます。 Power Automateの同じ接続ページの URL から名前を取得します。 URL の形式は
https://make.powerautomate.com/manage/environments/[Environment ID]/connections?apiName=shared_uiflow&connectionName=[Connection Name]。

注記

詳細については、「デスクトップフロー接続の作成」を参照してください。

ヒント

または、接続名の代わりに接続参照の論理名を接続の入力として使用します (次のセクションで説明する使用例)。接続参照は Dataverse テーブル connectionreference に格納され、「使用可能なデスクトップフローの一覧表示」セクションで詳しく説明されているデスクトップフローと同じ方法でプログラムで一覧表示できます。

詳細については、ソリューション内で接続参照を使用すると connectionreference テーブル/エンティティ参照を参照してください。

デスクトップフローをトリガーする要求

Authorization: Bearer eyJ0eXAiOi...
Accept: application/json

POST https://[Organization URI]/api/data/v9.2/workflows([Workflow ID])/Microsoft.Dynamics.CRM.RunDesktopFlow HTTP/1.1  
{
    "runMode": "attended",
    "runPriority": "normal",
    "connectionName": "[Connection Name]",
    "timeout": 7200,
    "inputs": "{\"Input1\":\"Value\", \"Input2\":\"Value\"}"
}

接続参照を使用してデスクトップフローをトリガーするように要求する

Authorization: Bearer eyJ0eXAiOi...
Accept: application/json

POST https://[Organization URI]/api/data/v9.2/workflows([Workflow ID])/Microsoft.Dynamics.CRM.RunDesktopFlow HTTP/1.1  
{
    "runMode": "attended",
    "runPriority": "normal",
    "connectionName": "[Connection Reference Logical Name]",
    "connectionType": 2,
    "timeout": 7200,
    "inputs": "{\"Input1\":\"Value\", \"Input2\":\"Value\"}"
}

デスクトップフローを起動するための要求からの応答

{
    "@odata.context": "https://[Organization URI]/api/data/v9.2/$metadata#Microsoft.Dynamics.CRM.RunDesktopFlowResponse",
    "flowsessionId": "d9687093-d0c0-ec11-983e-0022480b428a"
}

スクリプトの入力は、Power Automate ポータル (プレビュー) の実行の詳細ページで確認できます。

警告

API を使用する場合は、次の制限事項に注意してください。

ユーザー特権を持つアカウントを使用して、デスクトップフローの実行をトリガーします。実行を取り消すか、状態を照会するには、 所有者 特権が必要です。
Dataverse 偽装はサポートされていません。
入力フィールドのコンテンツサイズは 2 MB に制限されています。

スクリプトの完了時に通知を受け取る

オプションのパラメータ "callbackUrl" は、RunDesktopFlow アクションの本文で利用可能です。スクリプトの完了を通知したい場合に使用できます。スクリプトが完了すると、指定された URL に POST 要求が送信されます。

コールバックエンドポイントによって受信されたリクエスト

User-Agent: EnterpriseConnectors/1.0
Content-type: application/json; charset=utf-8
x-ms-workflow-id: [Workflow ID]
x-ms-run-id: [Flow session ID]

POST [yourCallbackURL]

{
    "statuscode": 4,
    "statecode": 0,
    "startedon": "2022-09-05T08:04:11Z",
    "completedon": "2022-09-05T08:04:41Z",
    "flowsessionid": "d9687093-d0c0-ec11-983e-0022480b428a"
}

コールバック URL パラメータが指定されていない場合、フローセッションのステータスは Dataverse(参照デスクトップフロー実行のステータスを取得する) からポーリングされる必要があります。

注記

コールバック URL パラメーターを指定した場合でも、ステータスポーリングをフォールバックメカニズムとして使用できます。
コールバックエンドポイントの処理はべき等である必要があります。
エンドポイントがサーバーエラー応答 (コード 500 以上) または「要求タイムアウト」応答 (コード 408) で応答した場合、POST 要求は 1 秒間隔で 3 回再試行されます。

コールバック URL パラメータの要件

サーバーには、現在の TLS スイートと暗号スイートが必要です。
HTTP プロトコルのみ許可されます。
localhost (loopback) へのアクセスは許可されません。
IP アドレスは使用できません。 DNS による名前解決を必要とする名前付き Web アドレスを使用する必要があります。
サーバーは AzureCloud サービスタグで指定されている Power Platform および Dynamics 365 サービスの IP アドレス値からの接続を許可する必要があります。

ヒント

コールバック呼び出しは認証されていないため、いくつかの予防策を講じる必要があります

コールバック通知を受信したら、フローセッション ID の有効性を確認します。 Dataverse は事実のソースです。
サーバー側でレート制限戦略を実装します。
複数の組織間でのコールバック URL の共有を制限するようにしてください。

デスクトップフローの実行をキャンセルする

トリガー機能と同様に、キューまたは実行中のデスクトップフローを取り消すこともできます。デスクトップフローをキャンセルするには、CancelDesktopFlowRun アクションを使用します。

デスクトップフローの実行を取り消す要求

Authorization: Bearer eyJ0eXAiOi...
Accept: application/json

POST https://[Organization URI]/api/data/v9.2/flowsessions(d9687093-d0c0-ec11-983e-0022480b428a)/Microsoft.Dynamics.CRM.CancelDesktopFlowRun HTTP/1.1

デスクトップフローを取り消す要求からの応答

HTTP/1.1 204 No Content

エラー

エラーが発生すると、応答は Dataverse のエラーメッセージと一致する異なる形式になります。 HTTP エラーコードとメッセージは、問題を理解するのに十分な情報を提供します。

HTTP/1.1 403 Forbidden

{
    "error": {
        "code": "0x80040220",
        "message": " Principal user (Id=526..., type=8) is missing prvReadworkflow privilege (Id=88...*)”
    }
}

既知の制限

接続ごとに 1 分あたり最大 70 個のデスクトップフローを実行できます。

フィードバック

このページはお役に立ちましたか?

Last updated on 2026-09-01

コードを使ったデスクトップ フローでの作業

前提条件

利用可能なデスクトップフローの一覧表示

デスクトップフローの取得要求

発行されていない (下書き) フローを含むデスクトップ フローを取得する要求

デスクトップ フローを取得リクエストへの応答

デスクトップ フローのスキーマを取得する

デスクトップ フローの入力スキーマを要求する

デスクトップ フローの入力スキーマの取得要求に対する応答

デスクトップ フローの出力スキーマを要求する

デスクトップ フローの出力スキーマの取得要求に対する応答

デスクトップフローの実行状況を取得する

デスクトップフローの実行状況を要求する

デスクトップフローの実行状況に対する応答

デスクトップ フロー出力の取得

デスクトップ フロー出力要求

デスクトップ フロー出力に関する要望への対応

デスクトップ フローの実行をトリガーする

デスクトップ フローをトリガーする要求

接続参照を使用してデスクトップ フローをトリガーするように要求する

デスクトップ フローを起動するための要求からの応答