教程：将应用程序安装到目标环境（预览）

2024-12-11

[本文为预发布文档，可能会发生变化。]

本教程旨在为 Power Platform 管理员提供支持，让他们可以利用 Power Platform API 来安装其租户具有权利的应用程序。这些应用程序应在环境>[环境名称]>资源>Dynamics 365 应用下的 Power Platform 管理中心可见。

在本教程中，将了解如何：

创建使用 Power Platform API 进行身份验证的 Power Automate 或逻辑应用工作流 (Azure)。
调用获取环境应用程序包 API 以检索可以安装到特定环境的应用程序列表
使用安装应用程序包 API 安装应用程序
轮询安装操作获取应用程序包安装状态 API 的状态
安装完成后通过电子邮件通知

在此示例场景中，客户希望将 Office 组安装到他们选择的特定环境中。

重要提示

Power Platform API 处于预览阶段。主机名和数据契约可能会在终结点正式发布时更改。到时，本文将使用最终的终结点详细信息进行更新。

选择可以使用 Power Platform API 进行身份验证的工具

以下信息提供了有关以编程方式连接到的详细信息 Power Platform 。本教程包括使用 Azure 逻辑应用作为在 Azure 空间中工作的管理员的通用客户端，以及本机 Power Platform CLI 示例。

Azure
Power Platform 命令行界面

创建工作流和设置变量

首先，在本教程中，我们使用逻辑应用工作流。另外也接受 Power Automate 流，以及您的公司更喜欢用于自动化的任何其他编排引擎。检索数据的所有调用都使用 RESTful API，因此任何支持 REST 的工具都适用于本教程。

访问 Azure 门户，然后创建一个新的逻辑应用并命名：

创建逻辑应用。

完成预配后，使用设计器编辑工作流并设置定期触发器以按您选择的计划运行：

设置定期触发器。

在本教程的其余部分，您需要环境 ID 和应用程序名称才能完成后续步骤：

环境 ID：要将软件包安装到的环境的 ID。此 ID 不是组织 ID。
应用程序名称：您尝试安装的应用程序的名称。

接下来，我们使用 Microsoft Entra API 进行身份验证并检索令牌 Power Platform 。如果您尚未完成 Microsoft Entra 设置，请参阅身份验证（预览）.

在本教程中，我们使用用户凭据和密码来获取令牌。

然后，我们在“解析 JSON”操作中使用此 JSON 架构将 Microsoft Entra 令牌响应解析为类型化对象：

{
    "properties": {
        "access_token": {
            "type": "string"
        },
        "expires_in": {
            "type": "integer"
        },
        "ext_expires_in": {
            "type": "integer"
        },
        "token_type": {
            "type": "string"
        }
    },
    "type": "object"
}

将 Microsoft Entra 令牌响应解析为强类型对象。

完成身份验证

使用 Power Platform CLI，您可以轻松完成特定 Dataverse 组织的身份验证。要进行身份验证，请选择现有的身份验证配置文件：

pac auth select --name "NameOfProfile"

选择身份验证配置文件。

有关详细信息，请参阅身份验证文章获取更深入的示例。

检索要安装的可用包

在本节中，我们将检索可安装到特定环境的应用程序列表。请确保已获取您的环境 ID，此环境已创建 Dataverse 数据库。

Azure
Power Platform 命令行界面

环境应用程序包终结点

现在，我们对 API 进行第一次调用 Power Platform 。我们将使用获取环境应用程序包 API 来检索我们可以为给定的 Dataverse 组织安装的所有可用包。请确保您使用的身份（无论是服务主体还是用户名/密码）都有权访问 Dataverse 和适当的安全角色。

GET https://api.powerplatform.com/appmanagement/environments/{environmentId}/applicationPackages?api-version=2022-03-01-preview

然后，我们使用此 JSON 架构和“解析 JSON”操作将回复解析为类型化对象：

{
    "properties": {
        "value": {
            "items": {
                "properties": {
                    "applicationDescription": {
                        "type": [
                            "string",
                            "null"
                        ]
                    },
                    "applicationId": {
                        "type": [
                            "string",
                            "null"
                        ]
                    },
                    "applicationName": {
                        "type": [
                            "string",
                            "null"
                        ]
                    },
                    "applicationVisibility": {
                        "type": [
                            "string",
                            "null"
                        ]
                    },
                    "catalogVisibility": {
                        "type": [
                            "string",
                            "null"
                        ]
                    },
                    "crmMaxVersion": {},
                    "crmMinversion": {
                        "type": [
                            "string",
                            "null"
                        ]
                    },
                    "customHandleUpgrade": {
                        "type": "boolean"
                    },
                    "endDateUtc": {
                        "type": [
                            "string",
                            "null"
                        ]
                    },
                    "errorDetails": {},
                    "id": {
                        "type": [
                            "string",
                            "null"
                        ]
                    },
                    "instancePackageId": {
                        "type": [
                            "string",
                            "null"
                        ]
                    },
                    "learnMoreUrl": {
                        "type": [
                            "string",
                            "null"
                        ]
                    },
                    "localizedDescription": {
                        "type": [
                            "string",
                            "null"
                        ]
                    },
                    "localizedName": {
                        "type": [
                            "string",
                            "null"
                        ]
                    },
                    "publisherId": {
                        "type": [
                            "string",
                            "null"
                        ]
                    },
                    "publisherName": {
                        "type": [
                            "string",
                            "null"
                        ]
                    },
                    "singlePageApplicationUrl": {},
                    "startDateUtc": {
                        "type": [
                            "string",
                            "null"
                        ]
                    },
                    "state": {
                        "type": [
                            "string",
                            "null"
                        ]
                    },
                    "supportedCountries": {
                        "items": {
                            "type": [
                                "string",
                                "null"
                            ]
                        },
                        "type": "array"
                    },
                    "uniqueName": {
                        "type": [
                            "string",
                            "null"
                        ]
                    },
                    "version": {
                        "type": [
                            "string",
                            "null"
                        ]
                    }
                },
                "required": [
                    "id",
                    "uniqueName",
                    "version",
                    "localizedDescription",
                    "localizedName",
                    "applicationId",
                    "applicationName",
                    "applicationDescription",
                    "singlePageApplicationUrl",
                    "publisherName",
                    "publisherId",
                    "learnMoreUrl",
                    "crmMinversion",
                    "crmMaxVersion",
                    "customHandleUpgrade",
                    "instancePackageId",
                    "state",
                    "catalogVisibility",
                    "applicationVisibility",
                    "errorDetails",
                    "startDateUtc",
                    "endDateUtc",
                    "supportedCountries"
                ],
                "type": "object"
            },
            "type": "array"
        }
    },
    "type": "object"
}

列出环境的应用程序

现在我们可以使用应用程序动词并列出该环境有权安装的可用应用程序。

pac application list --environment-id "YOUR_ENVIRONMENT_ID_HERE"

列出环境的应用。

有关详细信息，请参阅身份验证文章获取更深入的示例。

安装应用程序

现在我们可以从上一步中获取一个应用程序并进行安装。我们假设您要安装“Office 365 组”应用程序。选择 PackageUniqueName 字段中的值，在此例中是 Office365Groups，将在下一步中使用。

Azure
Power Platform 命令行界面

安装应用程序 API

我们使用安装应用程序 API 终结点来扳机键。在此示例中，请务必将 uniqueName 属性设置为 Office365Groups。

POST https://api.powerplatform.com/appmanagement/environments/{environmentId}/applicationPackages/{uniqueName}/install?api-version=2022-03-01-preview

请求正文包含前面步骤中的应用程序条目：

{
                "id": "ce3bab3c-ada1-40cf-b84b-49b26603a281",
                "uniqueName": "Office365Groups",
                "version": "2.9.0.3",
                "localizedDescription": "With Office 365 groups, you can collaborate with people across your company even if they aren’t Dynamics 365 users. Groups provide a single location to share conversations, meetings, documents, and more.",
                "localizedName": "Office 365 Groups",
                "applicationId": "2f17f077-4175-4d82-b82b-17cd8950b74f",
                "applicationName": "Office365Groups",
                "applicationDescription": "",
                "singlePageApplicationUrl": "",
                "publisherName": "Microsoft CRM Package",
                "publisherId": "255953fd-9ab8-4146-bfa1-859aae326ae9",
                "learnMoreUrl": "http://go.microsoft.com/fwlink/?LinkID=525719",
                "crmMinversion": "8.0",
                "crmMaxVersion": null,
                "customHandleUpgrade": false,
                "instancePackageId": null,
                "state": "None",
                "catalogVisibility": "None",
                "applicationVisibility": "All",
                "errorDetails": null,
                "startDateUtc": "2016-01-01T00:00:00Z",
                "endDateUtc": "2050-01-01T00:00:00Z",
                "supportedCountries": [
                    "AE",
                    "AL",
                    "AM",
                    "AO",
                    "VN",
                    "ZA",
                    "ZW"
                ]
            }

以下代码是一个示例回复：

{
        "id": "9a44d33b-6055-4c9b-aa4a-4c410a22e9ad",
        "packageId": "ce3bab3c-ada1-40cf-b84b-49b26603a281",
        "applicationId": "2f17f077-4175-4d82-b82b-17cd8950b74f",
        "applicationName": "Office365Groups",
        "applicationDescription": "",
        "singlePageApplicationUrl": "",
        "publisherName": "Microsoft CRM Package",
        "publisherId": "255953fd-9ab8-4146-bfa1-859aae326ae9",
        "packageUniqueName": "Office365Groups",
        "packageVersion": "2.9.0.3",
        "localizedDescription": "With Office 365 groups, you can collaborate with people across your company even if they aren’t Dynamics 365 users. Groups provide a single location to share conversations, meetings, documents, and more.",
        "localizedName": "Office 365 Groups",
        "learnMoreUrl": "http://go.microsoft.com/fwlink/?LinkID=525719",
        "termsOfServiceBlobUris": [
            "https://crmprodnam.blob.core.windows.net/preferredsolution/microsoft_tos_dbd53f75-b571-46ad-b9ce-21b5656b85dd_1?sv=2018-03-28&sr=c&sig=v5iBtDum0N6A0sqyyhIkPECibmpGOKGiSmmm3ALGIR0%3D&se=2022-03-23T19%3A35%3A59Z&sp=r"
        ],
        "applicationVisibility": "All",
        "lastOperation": {
            "state": "InstallRequested",
            "createdOn": "2022-03-22T19:35:59.7425066Z",
            "modifiedOn": null,
            "errorDetails": null,
            "statusMessage": null,
            "instancePackageId": "9a44d33b-6055-4c9b-aa4a-4c410a22e9ad",
            "operationId": "4fde996a-bf68-413c-b2bf-33f21a7e9afb"
        },
        "customHandleUpgrade": false
    }

然后，我们使用 Parse JSON 操作获取后续步骤的 operationID。

触发安装

现在，我们可以使用应用程序动词从上一步的输出安装应用。

pac application install --environment-id "YOUR_ENVIRONMENT_ID_HERE" --application-name "APP_UNIQUE_NAME_HERE"

触发安装。

有关详细信息，请参阅身份验证文章获取更深入的示例。

轮询操作状态

现在，我们通过使用上一步骤中的 operationID 每隔一段时间轮询一次来监视应用程序安装的进度。

Azure
Power Platform 命令行界面

使用 Until 控件

通过评估轮询 OperationID 的回复以查找任何终端状态（如 Canceled、 Failed 或 Succeeded），我们可以有效地监控流程的完成。这可以通过 Until 控件轻松完成，该控件会持续循环，直到满足此条件。

Until 控件。

我们使用 Application Install Status（应用程序安装状态）终结点来监视安装。请务必将 operationId 属性设置为上一步的属性。

GET https://api.powerplatform.com/appmanagement/environments/{environmentId}/operations/{operationId}?api-version=2022-03-01-preview

显示了一个示例输出：

{
  "status": "NotStarted",
  "createdDateTime": "2022-03-22T20:05:58.9414573Z",
  "lastActionDateTime": null,
  "error": null,
  "statusMessage": null,
  "operationId": "523b51a8-6af4-40cd-aa7d-86bddfa6697b"
}

从这里，我们可以评估状态，如果是终端值之一，我们可以中断循环。

发送电子邮件

现在监视已经结束，我们可以通过电子邮件作为示例活动共享结果。

发送有关活动状态的电子邮件 (v2)。

通过

教程：将应用程序安装到目标环境（预览）

选择可以使用 Power Platform API 进行身份验证的工具

创建工作流和设置变量

检索要安装的可用包

环境应用程序包终结点

安装应用程序

安装应用程序 API

轮询操作状态

使用 Until 控件

发送电子邮件

反馈

其他资源