Observação
O acesso a essa página exige autorização. Você pode tentar entrar ou alterar diretórios.
O acesso a essa página exige autorização. Você pode tentar alterar os diretórios.
[Este artigo faz parte da documentação de pré-lançamento e está sujeito a alterações.]
Este tutorial tem como objetivo habilitar os administradores do Power Platform para que eles possam aproveitar a API do Power Platform para instalar aplicativos dos quais seu locatário já tem direito. Esses aplicativos devem estar visíveis no centro de administração do Power Platform em Ambientes>[environment-name]>Recursos>aplicativos do Dynamics 365.
Neste tutorial, você aprenderá a:
- Criar um fluxo de trabalho do Power Automate ou de Aplicativos Lógicos (Azure) que autentica com a API do Power Platform.
- Chamar a API Obter Ambiente do Pacote de Aplicativos para recuperar a lista de aplicativos que você pode instalar em um ambiente específico
- Instalar o aplicativo usando a API Instalar Pacote de Aplicativos
- Pesquisar o status da operação de instalação da API Obter Ambiente do Pacote de Aplicativos
- Notificar por email assim que a instalação for concluída
Neste cenário de exemplo, um cliente deseja instalar Grupos do Office em um ambiente de sua escolha.
Importante
A API do Power Platform está em versão preliminar. O nome do host e os contratos de dados estão sujeitos a alterações no momento em que os terminais se tornam geralmente disponíveis. Nesse momento, este artigo será atualizado com os detalhes finais do ponto de extremidade.
Escolha uma ferramenta que possa autenticar com a API do Power Platform
As informações a seguir fornecem detalhes sobre como se conectar ao Power Platform programaticamente. Este tutorial inclui o uso de Aplicativos Lógicos do Azure como um cliente comum para administradores que trabalham no espaço do Azure e um exemplo de CLI nativa do Power Platform.
Criar o fluxo de trabalho e configurar as variáveis
Para começar, neste tutorial usamos um fluxo de trabalho Aplicativos Lógicos. Um fluxo do Power Automate também é aceitável, e qualquer outro mecanismo de orquestração que sua empresa prefira usar para automação. Todas as chamadas para recuperar os dados usam APIs RESTful, portanto, qualquer ferramenta que suporte REST funciona com este tutorial.
Visite o portal do Azure, crie um novo aplicativo lógico e dê um nome a ele:
Depois que o provisionamento for concluído, edite o fluxo de trabalho usando o Designer e configure um gatilho de recorrência para ser executado na agenda de sua escolha:
Para o restante deste tutorial, você precisará de um ID de ambiente e um nome de aplicativo para concluir as etapas subsequentes:
- Id do ambiente: O ID do ambiente no qual você instalaria o pacote. Este ID não é o ID da organização.
- Nome do aplicativo: O nome do aplicativo que você está tentando instalar.
Em seguida, autenticamos com Microsoft Entra e recuperamos um token para chamar a Power Platform API. Se você não concluiu a configuração do Microsoft Entra, consulte Autenticação (versão preliminar).
Neste tutorial, estamos usando uma credencial de usuário com senha para obter um token.
Em seguida, analisamos a resposta do token do Microsoft Entra em um objeto tipado usando este esquema JSON na ação 'Analisar JSON':
{
"properties": {
"access_token": {
"type": "string"
},
"expires_in": {
"type": "integer"
},
"ext_expires_in": {
"type": "integer"
},
"token_type": {
"type": "string"
}
},
"type": "object"
}
Recuperar pacotes disponíveis para instalação
Nesta seção, recuperamos a lista de aplicativos que você pode instalar em um ambiente específico. Certifique-se de ter sua ID de ambiente disponível, e que esse ambiente tenha um banco de dados do Dataverse criado.
Ponto de extremidade do pacote de aplicativos do ambiente
Agora fazemos nossa primeira chamada para a Power Platform API. Usaremos a API Obter Ambiente do Pacote de Aplicativos para recuperar todos os pacotes disponíveis que podemos instalar para a determinada organização do Dataverse. Verifique se de que a identidade que você está usando, seja uma entidade de serviço ou um nome de usuário/senha, tem acesso ao Dataverse e o direito de acesso adequado.
GET https://api.powerplatform.com/appmanagement/environments/{environmentId}/applicationPackages?api-version=2022-03-01-preview
Em seguida, analisamos o resposta em um objeto tipado usando este esquema JSON com a ação 'Analisar 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"
}
Instalar o aplicativo
Agora podemos pegar um dos aplicativos da etapa anterior e instalá-lo. Digamos que você queira instalar o aplicativo "Grupos do Office 365". Selecione o valor no campo PackageUniqueName, neste caso, é Office365Groups a ser utilizado na próxima etapa.
Instalar a API do aplicativo
Utilizamos o endpoint Instalar API do aplicativo para Gatilho a instalação. Certifique-se de definir a propriedade uniqueName para Office365Groups neste exemplo.
POST https://api.powerplatform.com/appmanagement/environments/{environmentId}/applicationPackages/{uniqueName}/install?api-version=2022-03-01-preview
E o corpo da solicitação tem a entrada do aplicativo do etapa anterior:
{
"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"
]
}
O código a seguir é um exemplo resposta:
{
"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
}
Em seguida, usamos a ação Analisar JSON para obter o operationID para nossas etapas subsequentes.
Pesquisar o status da operação
Agora monitoramos o progresso da instalação do aplicativo pesquisando de vez em quando usando o operationID do etapa anterior.
Usar o controle Until
Ao avaliar o resposta a partir da pesquisa do OperationID para qualquer status de terminal, como Cancelado, Falha ou Bem-sucedido, monitoramos efetivamente a conclusão do processo. Isso é feito facilmente com o controle Until, que faz um loop contínuo até que essa condição seja atendida.
Utilizamos o endpoint Status de instalação do aplicativo para monitorar a instalação. Certifique-se de definir a propriedade operationId na etapa anterior.
GET https://api.powerplatform.com/appmanagement/environments/{environmentId}/operations/{operationId}?api-version=2022-03-01-preview
Um exemplo de saída é mostrado:
{
"status": "NotStarted",
"createdDateTime": "2022-03-22T20:05:58.9414573Z",
"lastActionDateTime": null,
"error": null,
"statusMessage": null,
"operationId": "523b51a8-6af4-40cd-aa7d-86bddfa6697b"
}
A partir daqui, podemos avaliar o status e se um dos valores de terminal pode quebrar o loop.
Enviar como email
Agora que o monitoramento foi concluído, podemos compartilhar o resultado por email como uma atividade de exemplo.
