Tutoriel : Installer une application dans un environnement cible (version préliminaire)
[Cet article fait partie de la documentation en version préliminaire et peut faire l’objet de modifications.]
Ce tutoriel a pour but d’activer les administrateurs Power Platform afin qu’ils puissent profiter de l’API Power Platform pour installer des applications dont leur client dispose déjà de droit. Ces applications doivent être visibles dans le centre d’administration Power Platform sous Environnements>[nom-environnement]>Ressources>Applications Dynamics 365.
Dans ce didacticiel, vous allez découvrir comment :
- Créer un workflow Power Automate ou Logic Apps (Azure) qui s’authentifie avec l’API Power Platform.
- Appeler Obtenir l’API du package d’application de l’environnement pour récupérer la liste des applications que vous pouvez installer dans un environnement spécifique
- Installer l’application à l’aide de l’API d’installation du package d’application
- Interroger le statut de l’API du statut d’installation de l’opération d’installation Obtenir le package d’application
- Notifier par e-mail une fois l’installation terminée
Dans cet exemple de scénario, un client cherche à installer des groupes Office sur un environnement de son choix.
Important
L’API Power Platform est en version préliminaire. Le nom d’hôte et les contrats de données sont susceptibles d’être modifiés au moment où les terminaux deviennent généralement disponibles. À ce moment-là, cet article sera mis à jour avec les derniers détails de point de terminaison.
Choisir un outil qui peut s’authentifier avec l’API Power Platform
Vous trouverez ci-dessous des informations sur la connexion par programmation à Power Platform. Ce didacticiel inclut l’utilisation d’Azure Logic Apps en tant que client commun pour les administrateurs travaillant dans l’espace Azure, et un exemple de CLI Power Platform native.
Créer le workflow et configurer les variables
Pour commencer, dans ce didacticiel, nous utiliserons un flux de travail Logic Apps. Un flux Power Automate est également acceptable, ainsi que tout autre moteur d’orchestration que votre entreprise préfère utiliser pour l’automatisation. Tous les appels pour récupérer les données utiliseront des API RESTful, de sorte que tout outil prenant en charge REST fonctionnera avec ce didacticiel.
Visitez le portail Azure, puis créez une nouvelle application logique et donnez-lui un nom :
Une fois l’approvisionnement terminé, modifiez le flux de travail à l’aide du concepteur et configurez un déclencheur de récurrence pour qu’il s’exécute selon le calendrier de votre choix :
Pour le reste de ce didacticiel, vous aurez besoin d’un ID d’environnement et d’un nom d’application pour effectuer les étapes suivantes :
- Identifiant d’environnement : ID de l’environnement dans lequel vous installerez le package. Il ne s’agit pas de l’ID d’organisation.
- Nom de l’application : Nom unique de l’application que vous essayez d’installer.
Ensuite, nous nous authentifierons auprès de Microsoft Microsoft Entra et récupérerons un jeton pour appeler l’API Power Platform. Si vous n’avez pas terminé votre configuration Microsoft Entra, voir Authentification (version préliminaire).
Dans ce didacticiel, nous utilisons un identifiant utilisateur avec un mot de passe pour obtenir un jeton. Voici un exemple d’appel à Microsoft Entra ID :
Nous analysons ensuite la réponse de jeton Microsoft Entra dans un objet typé à l’aide de ce schéma JSON dans l’action ’Parse JSON’ :
{
"properties": {
"access_token": {
"type": "string"
},
"expires_in": {
"type": "integer"
},
"ext_expires_in": {
"type": "integer"
},
"token_type": {
"type": "string"
}
},
"type": "object"
}
Récupérer les packages disponibles à installer
Dans cette section, nous allons récupérer la liste des applications que vous pouvez installer dans un environnement spécifique. Assurez-vous d’avoir votre identifiant d’environnement disponible, et que cet environnement dispose d’une base de données Dataverse.
Point de terminaison du package d’application de l’environnement
Nous allons maintenant passer notre premier appel à l’API Power Platform. Nous allons utiliser Obtenir l’API du package d’application d’environnement pour récupérer tous les packages disponibles que nous pouvons installer pour l’organisation Dataverse. Assurez-vous que l’identité que vous utilisez, qu’il s’agisse d’un principal de service ou d’un nom d’utilisateur/mot de passe, a accès à Dataverse et au rôle de sécurité approprié.
GET https://api.powerplatform.com/appmanagement/environments/{environmentId}/applicationPackages?api-version=2022-03-01-preview
Nous analysons ensuite la réponse dans un objet fortement typé à l’aide de ce schéma JSON avec l’action « Parse 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"
}
Installer l’application
Nous pouvons maintenant prendre l’une des applications de l’étape précédente et l’installer. Supposons que vous vouliez installer l’application « Groupes Office 365 ». Sélectionnez la valeur dans le champ PackageUniqueName, dans ce cas, il s’agit d’Office365Groups à utiliser à l’étape suivante.
Installer l’API d’application
Nous utiliserons le point de terminaison de l’API d’installation de l’application pour déclencher l’installation. Veillez à bien définir la propriété uniqueName sur Office365Groups dans cet exemple.
POST https://api.powerplatform.com/appmanagement/environments/{environmentId}/applicationPackages/{uniqueName}/install?api-version=2022-03-01-preview
Et le corps de la requête contiendra l’entrée d’application de l’étape précédente :
{
"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"
]
}
Voici un exemple de réponse :
{
"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
}
Ensuite, nous utiliserons l’action Parse JSON pour obtenir l’operationID pour nos étapes suivantes.
Interroger le statut de l’opération
Nous allons maintenant surveiller la progression de l’installation de l’application en interrogeant de temps en temps à l’aide de l’operationID de l’étape précédente.
Utiliser le contrôle Until
En évaluant la réponse de l’interrogation de l’OperationID pour tout statut de terminal tel que Annulé, Échec ou Réussi, nous surveillerons efficacement la fin du processus. Cela se fait facilement avec le contrôle Until, qui bouclera en continu jusqu’à ce que cette condition soit remplie.
Nous utiliserons le point de terminaison du Statut d’installation de l’application pour surveiller l’installation. Veillez à bien définir la propriété operationId à partir de l’étape précédente.
GET https://api.powerplatform.com/appmanagement/environments/{environmentId}/operations/{operationId}?api-version=2022-03-01-preview
Un exemple de sortie est illustré ci-dessous :
{
"status": "NotStarted",
"createdDateTime": "2022-03-22T20:05:58.9414573Z",
"lastActionDateTime": null,
"error": null,
"statusMessage": null,
"operationId": "523b51a8-6af4-40cd-aa7d-86bddfa6697b"
}
À partir de là, nous pouvons évaluer le statut et s’il s’agit de l’une des valeurs terminales, nous pouvons rompre la boucle.
Envoyer un courrier électronique
Maintenant que la surveillance est terminée, nous pouvons partager le résultat par e-mail comme exemple d’activité.
