Créez une API personnalisée à l’aide de l’outil d’enregistrement de plug-in

Article
06/23/2023

L’outil d’enregistrement de plug-in (PRT) comprend un concepteur pour créer une API personnalisée. Le PRT est une application client Windows qui fait partie des outils de développement que vous pouvez télécharger à partir de NuGet. Consultez Outils de développement Dataverse pour obtenir des informations sur le téléchargement de ces outils.

Connexion à l’aide de Plug-in Registration Tool

Après avoir téléchargé Plug-in Registration Tool, cliquez sur le fichier PluginRegistration.exe pour l’ouvrir.
Cliquez sur Créer une nouvelle connexion pour vous connecter à votre instance.
Vérifiez que Office 365 est sélectionné.
Si vous vous connectez à l’aide d’un compte Microsoft autre que celui que vous utilisez actuellement, cliquez sur Afficher les paramètres avancés et saisissez vos informations d’identification. Sinon, laissez Connectez-vous en tant qu’utilisateur actuel sélectionné.
Si votre compte Microsoft donne accès à plusieurs environnements, sélectionnez Afficher la liste des organisations disponibles.
Cliquez sur Connexion.
Si vous avec sélectionné Afficher la liste des organisations disponibles, sélectionnez l’organisation à laquelle se connecter et cliquez sur Connexion.
Une fois connecté, vous verrez tous les plug-ins enregistrés existants, les activités de workflow personnalisées et les fournisseurs de données.

Créer une API personnalisée

Dans le menu Inscription, sélectionnez la commande Inscrire une nouvelle API personnalisée. Cela ouvrira le formulaire pour créer une API personnalisée.

Formulaire API personnalisée PRT

Utilisez les informations du tableau ci-dessous pour créer l’API personnalisée. Pour plus de détails, voir Colonnes de tableau d’API personnalisées

Important

Certaines options ne peuvent pas être modifiées après avoir enregistré l’API personnalisée. Assurez-vous que vous comprenez le but de chaque paramètre qui ne peut pas être modifié. Si vous devez modifier ce paramètre ultérieurement, vous devez supprimer et recréer l’API personnalisée. Cela supprimera également tous les paramètres de requête ou propriétés de réponse qui lui sont associés.

Étiquette	Description	Peut être modifiée
Nom d’affichage	Nom localisable.	Oui
Name	Nom convivial, non localisable.	Oui
Solution	Créez une solution ou sélectionnez-en une existante. La définition de cette valeur définira le préfixe de personnalisation approprié pour le champ Nom unique.	Oui
Nom unique	Nom de l’API personnalisée. Cette Valeur n’accepte que les caractères alphanumériques et aucun espace. Le nom complet inclut le préfixe de personnalisation déterminé en sélectionnant la solution.	Non
Description	Description localisable. À utiliser lorsque le message est exposé pour être appelé dans une application. Par exemple, en tant que Info-bulle.	Oui
Assembly	Facultatif. Sélectionnez un assembly qui contient un type de plug-in qui définira ce que fait l’API personnalisée.	Oui
Plugin	Facultatif. Sélectionnez un type de plug-in dans l’assembly sélectionné. Vous pourrez le définir plus tard.	Oui
Type d’étape de traitement personnalisée autorisée	Quels types d’étapes de traitement vous autorisez. Plus d’information : Sélectionnez un type d’étape de traitement personnalisé	Non
Type de liaison	Quel type de liaison d’entité. Pour plus d’informations : Sélectionner un type de liaison	Non
Nom logique de l’entité liée	Si vous sélectionnez Type de liaison Entité ou EntityCollection, vous devez entrer le nom logique de la table représentant ce type.	Non
Nom du privilège d’exécution	Le nom d’un privilège qui contrôlera si quelqu’un peut utiliser l’API. Ce doit être une valeur de Nom valide de la table de Privilège. Pour plus d’informations : Sécurisez votre API personnalisée avec un privilège	Oui
Fonction	Quand créer une fonction. Pour plus d’informations : Quand créer une fonction	Non
Privée	Indique si l’API personnalisée doit être privée. Pour plus d’informations : Quand rendre votre API personnalisée privée	Oui

Notes

Le concepteur d’API personnalisée PRT n’expose pas la propriété Enabled For Workflow (WorkflowSdkStepEnabled). Si vous souhaitez créer une API personnalisée qui fonctionnera pour les workflows, vous devez utiliser une méthode différente.
Le concepteur d’API personnalisée PRT n’expose pas la propriété gérée Is Customizable. Vous pouvez la définir dans Power Apps. Plus d’information : Personnalisation de l’API personnalisée

Vous pouvez continuer à ajouter Paramètres de requête et Propriétés de la réponse, ou enregistrez l’API personnalisée et ajoutez-les ultérieurement.

Paramètres de la création de la requête

Une API personnalisée n’est pas tenue d’avoir des paramètres de requête. À la création d’une API personnalisée ou à la modification d’une API existante, vous pouvez créer des paramètres de requête en cliquant sur + Ajouter un paramètre de requête. Cela ouvre le formulaire Paramètre.

Formulaire de création de paramètre de requête d’API personnalisée

Utilisez les informations du tableau ci-dessous pour créer le paramètre de requête. Pour plus de détails, voir Colonnes de tableau CustomAPIRequestParameter

Étiquette	Description	Peut être modifiée
Nom d’affichage	Nom d’affichage localisable.	Oui
Name	Nom principal du paramètre de requête de l’API personnalisée. Cette convention d’affectation de noms est recommandée pour différencier ce paramètre des autres qui partagent un Nom unique : `{Custom API Unique Name}.{Parameter UniqueName}`	Oui
Nom unique	Ce sera le nom du paramètre lorsque vous appellerez l’API personnalisée.	Non
Type	Sélectionnez le type de paramètre. Entier DateTime Decimal Entity EntityCollection EntityReference Float Integer Money Picklist String StringArray Guid	Non
Nom logique de l’entité	Lorsque Entité, EntityCollection, ou EntityReference est sélectionné comme Type, vous pouvez spécifier la table.	Non
Description	Description localisable.	Oui
Est facultatif	Indique si une valeur pour le paramètre est requise par l’appelant.	Non

Créer des propriétés de réponses

Une API personnalisée pour une action n’a pas besoin d’avoir de propriétés de réponse. À la création d’une API personnalisée ou à la modification d’une API existante, vous pouvez créer des propriétés de réponse en cliquant sur + Ajouter un paramètre de réponse. Cela ouvre le formulaire Paramètre.

Formulaire de création de propriété de réponse d’API personnalisée

Utilisez les informations du tableau ci-dessous pour créer la propriété de réponse. Pour plus de détails, voir Colonnes de tableau CustomAPIResponseProperty

Étiquette	Description	Peut être modifiée
Nom d’affichage	Nom d’affichage localisable.	Oui
Name	Nom principal de la propriété de réponse de l’API personnalisée. Cette convention d’affectation de noms est recommandée pour différencier ce paramètre des autres qui partagent un Nom unique : `{Custom API Unique Name}.{Property UniqueName}`	Oui
Nom unique	Ce sera le nom de la propriété renvoyée lorsque vous appelez l’API personnalisée.	Non
Type	Sélectionnez le type de la propriété. Entier DateHeure Decimal Entity EntityCollection EntityReference Float Integer Money Picklist String StringArray Guid	Non
Nom logique de l’entité	Si Entity ou EntityReference sont sélectionnés comme Type, vous pouvez spécifier la table. Vous ne pouvez pas spécifier un Nom d’entité logique si vous sélectionnez EntityCollection comme Type.	Non
Description	Description localisable.	Oui

Afficher une liste d’API personnalisées

Pour afficher une liste d’API personnalisées, à partir du menu Afficher, sélectionnez la commande Afficher par message.

La commande Afficher par message affichera l’API personnalisée

Tous les messages créés en tant qu’API personnalisée seront préfixés par (API personnalisée).

Supprimer l’API personnalisée

À l’affichage d’une liste d’API personnalisées, sélectionnez celle que vous souhaitez supprimer et cliquez sur la commande Désinscrire.

Supprimer une API personnalisée

Sinon, cliquez avec le bouton droit sur l’élément et sélectionnez Désinscrire dans le menu contextuel.

Mettre à jour les paramètres de demande d’API personnalisée ou les propriétés de réponse

Dans la liste des Paramètres de requête ou Propriétés de la réponse, sélectionnez cette colonne à modifier :

Colonne pour modifier les paramètres

Supprimer les paramètres de demande d’API personnalisée ou les propriétés de réponse

Dans la liste des Paramètres de requête ou Propriétés de la réponse, sélectionnez cette colonne à supprimer :

Paramètre Colonne à supprimer

Étapes suivantes

Si vous n’avez pas défini la propriété IsPrivate pour votre API personnalisée, après avoir créé votre API personnalisée, vous pouvez récupérer la définition de service à partir du Document CSDL $métadonnées à l’aide d’une requête GET, même depuis votre navigateur. Si l’URL de votre environnement est https://yourorg.crm.dynamics.com, vous pouvez taper cette URL dans le champ d’adresse de votre navigateur pour récupérer les $métadonnées : https://yourorg.crm.dynamics.com/api/data/v9.1/$metadata.

Recherchez le résultat pour trouver le nom de l’API personnalisée et vous trouverez l’action ou la fonction créée avec tout ComplexType associé pour représenter la valeur de retour. Par exemple :

<ComplexType Name="sample_CustomAPIExampleResponse">
    <Property Name="StringProperty"
        Type="Edm.String"
        Unicode="false"/>
</ComplexType>
<Action Name="sample_CustomAPIExample">
    <Parameter Name="StringParameter"
        Type="Edm.String"
        Nullable="false"
        Unicode="false"/>
    <ReturnType Type="mscrm.sample_CustomAPIExampleResponse"
        Nullable="false"/>
</Action>

Même si vous n’avez pas défini de Plug-in pour votre API personnalisée, vous pouvez la tester pour vérifier la signature. Toutes les propriétés de réponse renverront leurs valeurs par défaut car il n’y a pas de plug-in pour définir les valeurs. Pour plus d’informations : Appel d’API personnalisées

Si vous souhaitez ajouter un plug-in, vous devez l’écrire et enregistrer l’assembly. Ensuite, mettez à jour votre API personnalisée pour définir Assembly et Plug-in pour spécifier le code à exécuter en réponse à votre API personnalisée. Pour plus d’informations : Écrire un plug-in pour votre API personnalisée

Voir aussi

Créer et utiliser des API personnalisées
Créer une API personnalisée dans Power Apps
Créer une API personnalisée avec du code
Créer une API personnalisée avec des fichiers de solution
Créer vos propres messages
Colonnes de table d’API personnalisée