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

Créez une API personnalisée à l’aide du concepteur dans l’outil d’inscription de plug-in (PRT). Cet article explique comment définir une API personnalisée, ajouter des paramètres de requête et des propriétés de réponse, ainsi que les afficher, les mettre à jour ou les supprimer. Le PRT est une application cliente Windows qui fait partie des outils de développement que vous pouvez télécharger à partir de NuGet. Pour plus d’informations sur le téléchargement de ces outils, consultez les outils de développement Dataverse.

Se connecter à l’aide de l’outil de Plug-in Registration.

  1. Ouvrez l’outil d’inscription de plug-in en exécutant la commande PAC CLI pac tool prt .

  2. Sélectionnez +Créer une connexion pour vous connecter à votre environnement Dataverse.

  3. Vérifiez qu’Office 365 est activé.

  4. Si vous vous connectez à l’aide d’un compte Microsoft autre que celui que vous utilisez actuellement, sélectionnez Afficher avancé et entrez vos informations d’identification. Sinon, laissez la connexion en tant qu’utilisateur actuel sélectionnée.

    Note

    Si votre compte d’utilisateur utilise l’authentification multifacteur (MFA), vérifiez que la case à cocher Afficher avancé n’est pas cochée.

  5. Si votre compte Microsoft fournit l’accès à plusieurs environnements, sélectionnez Afficher la liste des organisations disponibles.

    Connexion à l’aide de l’outil d’inscription de plugin.

  6. Sélectionnez Se connecter.

  7. Si vous avez sélectionné Afficher la liste des organisations disponibles, sélectionnez l’organisation à laquelle vous souhaitez vous connecter et sélectionnez Connexion.

  8. Une fois connecté, vous verrez les plug-ins inscrits existants, les activités de flux de travail personnalisées et les fournisseurs de données.

    Afficher les plug-ins existants d’activités de flux de travail personnalisées.

Créer une API personnalisée

Dans le menu Inscrire , sélectionnez la nouvelle commande Inscrire une API personnalisée . Cette action ouvre le formulaire pour créer une API personnalisée.

Capture d’écran du formulaire pour créer une API personnalisée dans l’outil d’enregistrement des plug-ins.

Utilisez le tableau suivant pour créer l’API personnalisée. Pour plus d’informations, consultez les colonnes de table d’API personnalisées.

Important

Certaines options ne peuvent pas être modifiées après avoir enregistré l’API personnalisée. Veillez à comprendre l’objectif de chaque paramètre que vous ne pouvez pas modifier. Si vous devez ultérieurement modifier ce paramètre, vous devez supprimer et recréer l’API personnalisée. Cette action supprime également les paramètres de requête ou les propriétés de réponse qui lui sont associées.

Étiquette Description Peut être modifié
Nom d'affichage Un nom pouvant être localisé. Yes
Nom Nom convivial et non localisable. Yes
Solution Créez une solution ou sélectionnez-en une existante. Définir cette valeur définit le préfixe de personnalisation approprié pour le champ Nom unique. Yes
Nom unique Nom de l’API personnalisée. Cette valeur ne doit contenir que des caractères alphanumériques et aucun espace.
Le nom complet inclut le préfixe de personnalisation déterminé en sélectionnant la solution.		 N°
Description La description localisable. À utiliser lorsque le message est disponible pour être appelé dans une application. Par exemple, en tant que Info-bulle. Yes
Assemblage Facultatif. Sélectionnez un assembly qui contient un type de plug-in qui définit ce que fait l’API personnalisée. Yes
Plug-in Facultatif. Sélectionnez un type de plug-in dans l’assembly sélectionné. Vous pouvez définir cette valeur ultérieurement. Yes
Type d’étape de traitement personnalisé autorisé Types d’étapes de traitement autorisés Plus d’informations : Sélectionner un type d’étape de traitement personnalisé N°
Type de liaison Quel type de liaison d’entité. Plus d’informations : Sélectionner un type de liaison N°
Nom logique de l’entité liée Si vous sélectionnez Type de liaisonEntité ou EntityCollection, entrez le nom logique de la table représentant ce type. N°
Nom du privilège d'exécution Nom d’un privilège qui contrôle si quelqu’un peut utiliser l’API. Ce nom doit être une valeur Name valide de la table Privilege. Plus d’informations : Sécuriser votre API personnalisée en exigeant un privilège Yes
Fonction Indique s’il faut créer une fonction. Plus d’informations : Quand créer une fonction N°
Private Indique si l’API personnalisée doit être privée. Plus d’informations : Quand rendre votre API personnalisée privée Yes

Note

  • Le concepteur d’API personnalisé PRT n’expose pas la propriété Enabled For Workflow (WorkflowSdkStepEnabled). Si vous souhaitez créer une API personnalisée qui fonctionne pour Workflows, utilisez une autre méthode.
  • Le concepteur d’API personnalisée de PRT n’expose pas la propriété gérée Is Customizable . Vous pouvez définir cette propriété dans Power Apps. Pour plus d’informations, consultez Personnalisation d’API personnalisée.

Vous pouvez continuer à ajouter des paramètres de requête et des propriétés de réponse, ou enregistrer l’API personnalisée et les ajouter ultérieurement.

Créer des paramètres de requête d’API personnalisés

Une API personnalisée ne nécessite pas de paramètres de requête. Lors de la création ou de la modification d’une API personnalisée, vous pouvez ajouter des paramètres de requête en sélectionnant + Ajouter un paramètre de requête. Cette sélection ouvre le formulaire Paramètre .

Capture d’écran du formulaire Paramètre utilisé pour créer un paramètre de demande d’API personnalisé.

Utilisez le tableau suivant pour créer le paramètre de requête. Pour plus d’informations, consultez Colonnes de table CustomAPIRequestParameter.

Étiquette Description Peut être modifié
Nom d'affichage Nom d'affichage localisable. Yes
Nom Nom principal du paramètre de requête d’API personnalisée. Utilisez cette convention d’affectation de noms pour différencier ce paramètre des autres paramètres qui partagent un nom unique commun : {Custom API Unique Name}.{Parameter UniqueName} Yes
Nom unique Nom du paramètre lorsque vous appelez l’API personnalisée. N°
Type Sélectionnez le type du paramètre.
Booléen
Date et heure
Décimal
Entité
EntityCollection
EntityReference
Flottant
Entier
Argent
Prélèvement
String
StringArray
GUID
 N°
Nom d’entité logique Lorsque vous sélectionnez Entity, EntityCollection ou EntityReference comme type, spécifiez la table. N°
Description Description localisable. Yes
Est facultatif Indique si l’appelant doit fournir une valeur pour le paramètre. N°

Créer des propriétés de réponse d’API personnalisées

Une API personnalisée pour une action ne nécessite aucune propriété de réponse. Lors de la création d’une API personnalisée ou de la modification d’une API existante, vous pouvez créer de nouvelles propriétés de réponse en sélectionnant + Ajouter un paramètre de réponse. Cette option ouvre le formulaire Paramètre.

Capture d’écran du formulaire Paramètre utilisé pour créer une propriété de réponse d’API personnalisée.

Utilisez le tableau suivant pour créer la propriété de réponse. Pour plus d’informations, consultez CustomAPIResponseProperty Table Columns.

Étiquette Description Peut être modifié
Nom d'affichage Nom d'affichage localisable. Yes
Nom Nom principal de la propriété de réponse d’API personnalisée. Utilisez cette convention d’affectation de noms pour différencier ce paramètre des autres paramètres qui partagent un nom unique commun : {Custom API Unique Name}.{Property UniqueName} Yes
Nom unique Ce nom est la propriété retournée lorsque vous appelez l’API personnalisée. N°
Type Sélectionnez le type de la propriété.
Booléen
Date et heure
Décimal
Entité
EntityCollection
EntityReference
Flottant
Entier
Argent
Prélèvement
String
StringArray
GUID
 N°
Nom d’entité logique Lorsque vous sélectionnez Entity ou EntityReference comme type, spécifiez le tableau. Vous ne pouvez pas spécifier de nom d’entité logique lorsque vous choisissez EntityCollection comme type. N°
Description Description localisable. Yes

Afficher une liste d’API personnalisées

Pour afficher une liste d’API personnalisées, sélectionnez la commande Afficher par message dans le menu Affichage .

Capture d’écran de la commande Afficher par message dans le menu Affichage montrant les API personnalisées.

Tous les messages que vous avez créés via une API personnalisée sont préfixés par (API personnalisée).

Supprimer une API personnalisée

Lorsque vous affichez une liste d’API personnalisées, sélectionnez l’API que vous souhaitez supprimer et sélectionnez Désinscrire.

Capture d’écran de la commande Désinscrire utilisée pour supprimer une API personnalisée sélectionnée.

Vous pouvez également cliquer avec le bouton droit sur l’élément et sélectionner Désenregistrer dans le menu contextuel.

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

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

Capture d’écran de la colonne utilisée pour modifier un paramètre de requête d’API personnalisé ou une propriété de réponse.

Supprimez les paramètres de requête d’API personnalisés ou les propriétés de réponse

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

Capture d’écran de la colonne utilisée pour supprimer un paramètre de requête d’API personnalisé ou une propriété de réponse.

Étapes suivantes

Si vous ne définissez pas la propriété IsPrivate de votre API personnalisée, vous pouvez récupérer la définition de service après avoir créé votre API personnalisée. Utilisez une GET requête pour obtenir le document CSDL $metadata, même à partir de votre navigateur. Si l’URL de votre environnement est https://yourorg.crm.dynamics.com, tapez cette URL dans le champ d’adresse de votre navigateur pour récupérer le $metadata : https://yourorg.crm.dynamics.com/api/data/v9.1/$metadata.

Recherchez le résultat pour trouver le nom de l’API personnalisée. Vous trouverez l’action ou la fonction créée avec n’importe quel 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 ne définissez pas de plug-in pour votre API personnalisée, vous pouvez le tester pour vérifier la signature. Les propriétés de la réponse retournent leurs valeurs par défaut, car il n’existe aucun plug-in pour définir les valeurs. Pour plus d’informations, consultez Appel d’API personnalisées.

Si vous ajoutez un plug-in, vous devez l’écrire et enregistrer l’assembly. Ensuite, mettez à jour votre API personnalisée pour définir l’assembly et le plug-in pour spécifier le code à exécuter en réponse à votre API personnalisée. Pour plus d’informations, consultez É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ées

  • Dernière mise à jour :