Partager via

Créer une API personnalisée avec des fichiers de solution

  • Article

Notes

Cette rubrique est une rubrique avancée qui suppose que vous avez déjà lu et compris ces rubriques :

Bien que vous puissiez créer des API personnalisées via un concepteur ou avec du code, vous pouvez également les définir en utilisant des fichiers d’une solution. L’utilisation de fichiers dans une solution peut être l’option préférée pour les éditeurs de solutions qui appliquent les bonnes pratiques recommandées de la gestion du cycle de vie des applications (ALM).

Un fichier de solution est un fichier compressé (zip) qui a été exporté à partir d’une instance Microsoft Dataverse. Le contenu de ce fichier peut être extrait et les composants archivés dans un référentiel source. Le contenu peut être édité puis compressé à nouveau. Les modifications appliquées à la solution font partie de la solution et sont créées lors de l’importation de celle-ci.

Notes

Ces processus sont généralement automatisés avec des outils et des processus qui dépassent le cadre de la présente rubrique. Cette rubrique se concentre sur le scénario simple de création d’une API personnalisée en manipulant manuellement les fichiers extraits d’une solution, pour montrer comment utiliser les données des fichiers pour créer une API personnalisée. En savoir plus : Contrôle de code source avec les fichiers de solution

Étape 1 : Créer une solution non gérée

Vous ne devez pas essayer de composer un fichier de solution manuellement. Utilisez les outils de Power Apps pour générer un fichier de solution. Suivez les étapes décrites dans les articles suivants pour créer et exporter une solution. La solution ne doit pas nécessairement contenir des composants de solution.

  1. Créer une solution

    Pour cet exemple, la solution est définie simplement comme ceci :

    Une solution vide.

  2. Exporter des solutions

    Pour cet exemple, assurez-vous d’exporter une solution non gérée. Une solution gérée est la valeur par défaut.

    Option pour sélectionner l’exportation d′une solution non gérée.

Vous pouvez trouver le fichier exporté dans votre dossier de téléchargements. Il a un nom dépendant du nom et de la version de la solution. Dans le cas présent : CustomAPIExample_1_0_0_2.zip.

Étape 2 : Extraire le contenu de la solution et mettre à jour la version

La solution est un fichier compressé (zip).

  1. Cliquez avec le bouton droit sur le fichier et choisissez Extraire tout... dans le menu contextuel.

    Vous ne devriez voir que les trois fichiers suivants dans le dossier :

    • [Content_Types].xml
    • customizations.xml
    • solution.xml

  2. Ouvrez le fichier solution.xml et localisez l’élément Version.

    <ImportExportXml version="9.1.0.23474" SolutionPackageVersion="9.1" languagecode="1033" generatedBy="CrmLive" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
  <SolutionManifest>
    <UniqueName>CustomAPIExample</UniqueName>
    <LocalizedNames>
      <LocalizedName description="Custom API Example" languagecode="1033" />
    </LocalizedNames>
    <Descriptions />
    <Version>1.0.0.1</Version>

  3. Mettez à jour la valeur de 1. Dans cet exemple, c’est <Version>1.0.0.2</Version>.

  4. Enregistrez le fichier.

Étape 3 : Ajouter la définition de l’API personnalisée

Toutes les API personnalisées d’une solution se trouvent dans un dossier nommé customapis. Dans ce dossier, chaque API personnalisée sera dans un dossier nommé d’après la propriété UniqueName de l’API personnalisée. Dans le dossier, les données représentant l’API personnalisée se trouvent dans un fichier XML nommé customapi.xml

  1. Dans le dossier contenant les fichiers extraits, créez un nouveau dossier nommé customapis.

  2. Dans le dossier customapis, créez un dossier portant le UniqueName de l’API personnalisée que vous souhaitez créer. Pour cet exemple, nous utilisons sample_CustomAPIExample.

  3. Dans le dossier sample_CustomAPIExample que vous avez créé, créez un fichier nommé customapi.xml.

  4. Modifiez le fichier customapi.xml pour définir les propriétés de l’API personnalisée que vous souhaitez créer. Pour cet exemple, nous utilisons le fichier xml suivant :

    <customapi uniquename="sample_CustomAPIExample">
  <allowedcustomprocessingsteptype>0</allowedcustomprocessingsteptype>
  <bindingtype>0</bindingtype>
  <boundentitylogicalname />
  <description default="A simple example of a custom API">
    <label description="A simple example of a custom API" languagecode="1033" />
  </description>
  <displayname default="Custom API Example">
    <label description="Custom API Example" languagecode="1033" />
  </displayname>
  <iscustomizable>0</iscustomizable>
  <executeprivilegename />
  <isfunction>0</isfunction>
  <isprivate>0</isprivate>
  <name>sample_CustomAPIExample</name>
  <plugintypeid />
</customapi>

Voir les informations dans Colonnes de tableau d’API personnalisées pour définir les valeurs des éléments.

Définir une relation avec un type de plug-in (facultatif)

Si vous disposez déjà d’un type de plug-in que vous souhaitez associer à cette API personnalisée, vous pouvez inclure une référence à celui-ci dans cette définition en ajoutant l’élément suivant dans l’élément <customapi> :

<plugintypeid>
   <plugintypeexportkey>{Add the GUID value of the plug-in type export key}</plugintypeexportkey>
</plugintypeid>

OU

<plugintypeid>
 <plugintypeid>{Add the GUID value of the plug-in type id}</plugintypeid>
</plugintypeid>

Notes

L’une ou l’autre valeur fonctionne, mais nous vous recommandons d’utiliser plugintypeexportkey.

Vous pouvez récupérer les valeurs PluginTypeExportKey et PluginTypeId à l’aide d’une requête d’API Web comme celle-ci, où vous connaissez le nom du type de plug-in :

GET [Organization Uri]/api/data/v9.2/plugintypes?$select=name,plugintypeid,plugintypeexportkey&$filter=contains(name,'MyPlugin.TypeName')

Étape 4 : Ajouter des paramètres de requête d’API personnalisée

Toutes les définitions des paramètres de requête pour l’API personnalisée sont incluses dans un dossier appelé customapirequestparameters. Dans ce dossier, chaque paramètre de requête de l’API personnalisée sera dans un dossier nommé d’après la propriété de paramètre de requête UniqueName de l’API personnalisée.

  1. Si votre API personnalisée a des paramètres de requête, dans le dossier de l’API personnalisée que vous avez créé à l’étape précédente, créez un dossier nommé customapirequestparameters.
  2. Pour chaque paramètre de requête d’API personnalisé, créez un nouveau dossier en utilisant la propriété UniqueName du paramètre de requête de l’API personnalisée. Pour cet exemple, nous utilisons StringParameter.
  3. Dans le dossier, ajoutez un fichier xml nommé customapirequestparameter.xml.
  4. Modifiez le fichier customapirequestparameter.xml pour définir les propriétés de l’API personnalisée que vous souhaitez créer. Pour cet exemple, nous utilisons les valeurs suivantes :
<customapirequestparameter uniquename="StringParameter">
  <description default="The StringParameter request parameter for custom API Example">
    <label description="The StringParameter request parameter for custom API Example" languagecode="1033" />
  </description>
  <displayname default="Custom API Example String Parameter">
    <label description="Custom API Example String Parameter" languagecode="1033" />
  </displayname>
  <iscustomizable>0</iscustomizable>
  <isoptional>0</isoptional>
  <logicalentityname />
  <name>sample_CustomAPIExample.StringParameter</name>
  <type>10</type>
</customapirequestparameter>

Voir les informations dans Colonnes de table CustomAPIRequestParameter pour définir les valeurs des éléments.

Étape 5 : Ajouter des propriétés de réponse de l’API personnalisée

Toutes les définitions des propriétés de réponse pour l’API personnalisée sont incluses dans un dossier appelé customapiresponseproperties. Dans ce dossier, chaque propriété de réponse de l’API personnalisée sera dans un dossier nommé d’après la propriété UniqueName de la propriété de réponse de l’API personnalisée.

  1. Si votre API personnalisée a des propriétés de réponse, dans le dossier de l’API personnalisée que vous avez créé à l’Étape 3 : Ajouter la définition de l’API personnalisée, créez un dossier nommé customapiresponseproperties.
  2. Pour chaque propriété de réponse de l’API personnalisé, créez un nouveau dossier en utilisant la propriété UniqueName de la propriété de réponse de l’API personnalisée. Pour cet exemple, nous utilisons StringProperty.
  3. Dans le dossier, ajoutez un fichier xml nommé customapiresponseproperty.xml.
  4. Modifiez le fichier customapiresponseproperty.xml pour définir les propriétés de l’API personnalisée que vous souhaitez créer. Pour cet exemple, nous utilisons les valeurs suivantes :
<customapiresponseproperty uniquename="StringProperty">
  <description default="The StringProperty response property for custom API Example">
    <label description="The StringProperty response property for custom API Example" languagecode="1033" />
  </description>
  <displayname default="Custom API Example String Property">
    <label description="Custom API Example String Property" languagecode="1033" />
  </displayname>
  <iscustomizable>0</iscustomizable>
  <logicalentityname />
  <name>sample_CustomAPIExample.StringProperty</name>
  <type>10</type>
</customapiresponseproperty>

Voir les informations dans Colonnes de table CustomAPIResponseProperty pour définir les valeurs des éléments.

Notes

Bien que le schéma des paramètres de requête et des propriétés de réponse soit très similaire, notez que isoptional n’est pas valide pour une propriété de réponse et provoquera une erreur lorsque vous essaierez d’importer la solution.

Étape 6 : Compresser les fichiers pour créer un nouveau fichier de solution

  1. Revenez au dossier dans lequel vous avez extrait le fichier de solution d’origine à l’Étape 2 : Extraire le contenu de la solution et mettre à jour la version

  2. Sélectionnez tous les fichiers extraits et le dossier customapis que vous avez créé.

    Les fichiers de solution sélectionnés.

  3. Cliquez avec le bouton droit sur les fichiers sélectionnés et choisissez Envoyer vers > Dossier compressé (zippé).

  4. Vous pouvez renommer le fichier résultant comme vous le souhaitez. Pour cet exemple, renommez-le pour qu’il corresponde au fichier de solution exporté d’origine : CustomAPIExample_1_0_0_2.zip.

Étape 7 : Importer la solution avec la définition de votre API personnalisée

  1. Revenez à Power Apps et sélectionnez Solutions.

  2. Sélectionnez Importer et suivez les instructions pour sélectionner le fichier de solution que vous avez créé à l’étape précédente.

    Importer le fichier de solution.

    Notes

    Si vous voyez un avertissement disant Cette version du package de solution est déjà installée, vous ne devez pas avoir mis à jour l’élément Version du fichier solution.xml comme décrit à l’Étape 2 : Extraire le contenu de la solution et mettre à jour la version.

  3. Vous devez voir un avertissement disant Ce package de solution contient une mise à jour pour une solution déjà installée. Sélectionnez Importer pour continuer.

  4. Attendez quelques minutes que l’importation de la solution se termine.

Notes

Il est possible que vous voyiez une erreur si une autre solution est installée en même temps. Pour plus d’informations : L’installation ou la suppression de la solution a échoué en raison de l’installation ou de la suppression d’une autre solution en même temps

Étape 8 : Vérifier que l’API personnalisée a été ajoutée à votre solution

Ouvrez la solution que vous avez créée et vérifiez que l’API personnalisée et les paramètres de requête et les propriétés de réponse associés sont inclus.

Illustration que le composant de la solution a été installé avec succès.

À ce stade, vous pouvez tester votre API en suivant les étapes décrites dans Tester votre API personnalisée

Mettre à jour une API personnalisée dans une solution

Après avoir livré une solution contenant une API personnalisée, vous souhaitez peut-être apporter des modifications à l’API personnalisée dans votre solution non gérée. Vous pouvez ajouter de nouveaux paramètres ou propriétés de réponse et apporter des modifications aux colonnes qui prennent en charge la mise à jour, telles que displayname et description.

Important

Vous ne pouvez pas introduire de modification dans une API personnalisée dans une solution qui modifie l’une des propriétés qui ne peuvent pas être modifiées après leur enregistrement. Lorsque vous installez une version plus récente d’une solution qui contient une définition d’une API personnalisée, elle tente de mettre à jour les propriétés de l’API personnalisée, des paramètres de demande de l’API personnalisée et de la réponse de l’API personnalisée. Une mise à jour de solution revient à essayer de mettre à jour l’API personnalisée à l’aide de toute autre méthode.

Les propriétés suivantes des fichiers de solution ne peuvent pas être modifiées après la création d’une API personnalisée :

  • Propriétés d’API personnalisées :
    • allowedcustomprocessingsteptype
    • bindingtype
    • boundentitylogicalname
    • isfunction
    • uniquename
    • workflowsdkstepenabled
  • Propriétés RequestParameter d’API personnalisée :
    • isoptional
    • logicalentityname
    • type
    • uniquename
  • Propriétés de réponse de l’API personnalisée :
    • logicalentityname
    • type
    • uniquename

Pour plus d’informations : Tables CustomAPI

Fournir des étiquettes localisées avec la solution

Au lieu d’utiliser le processus décrit dans Valeurs des étiquettes localisées, si vous mettez à jour les fichiers de solution pour les entités API personnalisées, vous pouvez fournir des traductions directement dans ces fichiers. Par exemple, si vous souhaitez fournir des étiquettes localisées en japonais pour votre API personnalisée, vous pouvez les fournir pour les propriétés description et displayname, comme indiqué ci-dessous :

<customapi uniquename="sample_CustomAPIExample">
  <allowedcustomprocessingsteptype>0</allowedcustomprocessingsteptype>
  <bindingtype>0</bindingtype>
  <description default="A simple example of a custom API">
    <label description="A simple example of a custom API" languagecode="1033" />
    <label description="カスタムAPIの簡単な例" languagecode="1041" />
  </description>
  <displayname default="Custom API Example">
    <label description="Custom API Example" languagecode="1033" />
    <label description="カスタムAPIの例" languagecode="1041" />
  </displayname>
  <iscustomizable>0</iscustomizable>
  <isfunction>0</isfunction>
  <name>sample_CustomAPIExample</name>
</customapi>

Voir aussi

Créer et utiliser des API personnalisées
Tables CustomAPI
Créer une API personnalisée à l’aide de l’outil d’enregistrement de plug-in
Créer une API personnalisée dans Power Apps
Créer une API personnalisée avec du code
Créer vos propres messages

Notes

Pouvez-vous nous indiquer vos préférences de langue pour la documentation ? Répondez à un court questionnaire. (veuillez noter que ce questionnaire est en anglais)

Le questionnaire vous prendra environ sept minutes. Aucune donnée personnelle n’est collectée (déclaration de confidentialité).