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

Cet article montre comment créer une API personnalisée en ajoutant des fichiers de définition à un projet de solution Microsoft Dataverse. Cette approche est utile pour les éditeurs de solutions qui stockent les fichiers de solution dans le contrôle de code source et appliquent des pratiques de gestion du cycle de vie des applications (ALM).

Utilisez Microsoft Power Platform CLI pour initialiser le projet de solution, générer le package de solution et l’importer dans un environnement Dataverse. Vous n’avez pas besoin de créer ou d’exporter d’abord une solution vide.

Prerequisites

• Installez Microsoft Power Platform CLI.
• Installez un kit de développement logiciel (SDK) .NET qui inclut la dotnet commande.
• Vous avez accès à un environnement Dataverse où vous avez des privilèges pour importer des solutions.

Étape 1 : Initialiser un projet de solution

Dans le dossier dans lequel vous souhaitez créer le projet, exécutez la commande suivante :

pac solution init --publisher-name Samples --publisher-prefix sample --outputDirectory CustomAPIExample

La commande pac solution init crée un CustomAPIExample dossier qui contient :

• CustomAPIExample.cdsproj: fichier projet de solution Dataverse.
• src\Other\Solution.xml: la solution et la définition de l’éditeur.
• src\Other\Customizations.xml: Définition des personnalisations de la solution.
• src\Other\Relationships.xml: Définition des relations de solution.

Le nom du répertoire de sortie devient le nom unique de la solution. Vérifiez les valeurs src\Other\Solution.xml générées avant de continuer.

Étape 2 : 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 se trouve dans un dossier nommé après la propriété d’API UniqueName personnalisée. Les données représentant l’API personnalisée se trouve dans un fichier XML nommé customapi.xml.

1. Dans le CustomAPIExample\src dossier, créez un 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, utilisez le code 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, incluez une référence à celle-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>

Pour récupérer les valeurs PluginTypeExportKey et PluginTypeId , utilisez une requête d’API web lorsque 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 3 : Ajouter des paramètres de requête d’API personnalisés

Incluez les définitions des paramètres de requête pour l’API personnalisée dans un dossier appelé customapirequestparameters. Dans ce dossier, chaque paramètre de requête d’API personnalisé se trouve dans un dossier nommé après sa UniqueName propriété.

1. Si votre API personnalisée a des paramètres de requête, dans le CustomAPIExample\src\customapis\sample_CustomAPIExample dossier, 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>
   

   Consultez les colonnes de la table des paramètres de requête d’API personnalisées pour définir les valeurs des éléments.

Étape 4 : Ajouter des propriétés de réponse d’API personnalisées

Vous définissez les propriétés de réponse de l’API personnalisée dans un dossier nommé customapiresponseproperties. Chaque propriété de réponse d’API personnalisée réside dans son propre dossier, qui est nommé après la valeur de UniqueName la propriété.

1. Si votre API personnalisée inclut des propriétés de réponse, créez un customapiresponseproperties dossier dans CustomAPIExample\src\customapis\sample_CustomAPIExample.

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. Ajoutez un fichier XML nommé customapiresponseproperty.xml au dossier.

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>
   

   Pour définir les valeurs des éléments, consultez les colonnes de la table des propriétés de réponse d’API personnalisées.

Étape 5 : Passer en revue la structure du projet de solution

Votre projet de solution doit avoir cette structure :

CustomAPIExample
|   CustomAPIExample.cdsproj
|
\---src
    +---customapis
    |   \---sample_CustomAPIExample
    |       |   customapi.xml
    |       |
    |       +---customapirequestparameters
    |       |   \---StringParameter
    |       |           customapirequestparameter.xml
    |       |
    |       \---customapiresponseproperties
    |           \---StringProperty
    |                   customapiresponseproperty.xml
    |
    \---Other
            Customizations.xml
            Relationships.xml
            Solution.xml

Étape 6 : Générer la solution

À partir du dossier du CustomAPIExample projet, exécutez :

dotnet build

Le processus de génération restaure les packages requis et crée le package de solution non managé à l’adresse bin\Debug\CustomAPIExample.zip.

Étape 7 : Importer la solution

Si vous avez déjà des profils d’authentification, utilisez la liste d’authentification pac et l’authentification pac pour sélectionner le profil de l’environnement cible.

Si vous n’avez aucun profil d’authentification, apprenez à vous connecter à votre environnement.

1. À partir du dossier du CustomAPIExample projet, importez et publiez la solution :

   pac solution import --path .\bin\Debug\CustomAPIExample.zip --publish-changes
   

Attendez la fin de l’importation.

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

Dans Power Apps, ouvrez la solution CustomAPIExample 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.

À ce stade, vous pouvez tester votre API en suivant les étapes décrites dans Tester votre API personnalisée. À 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.

Avant de générer et d’importer une solution mise à jour, définissez la révision sur une valeur supérieure à la version déjà installée. Par exemple, exécutez ces commandes à partir du dossier du projet de solution :

pac solution version --revisionversion 2 --solutionPath .\src
dotnet build
pac solution import --path .\bin\Debug\CustomAPIExample.zip --publish-changes

Fournir des étiquettes localisées à la solution

Au lieu d’utiliser le processus décrit dans les valeurs d’étiquette localisées, vous pouvez fournir des traductions directement dans les fichiers de solution pour les entités API personnalisées. Par exemple, si vous souhaitez fournir des étiquettes localisées japonaises pour votre API personnalisée, vous pouvez les fournir pour les propriétés et displayname les description propriétés, comme indiqué dans l’exemple suivant :

<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éez 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
• Microsoft Power Platform groupe de commandes de la solution CLI