次の方法で共有

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

  • [アーティクル]

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

前提条件

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

重要

この記事では、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

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

{
    "@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",
}

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

デスクトップ フローに出力がある場合、出力フィールドにクエリを発行し、出力を取得することができます。

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

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。 この ID は、この記事の前の利用可能なデスクトップ フローの一覧セクションで概要を説明したように、API 経由で取得することができます。

    チップ

    または、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]。

    Note

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

    チップ

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

    詳細については、ソリューション内で接続参照を使用する と 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(参照デスクトップ フロー実行のステータスを取得する) からポーリングされる必要があります。

Note

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

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

チップ

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

  • コールバック通知を受信したら、フロー セッション 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 のデスクトップ フローの実行がサポートされています。