Interroger les données à l’aide de l’API web des portails

Vous pouvez utiliser les opérations d’API Web disponibles dans les portails. Les opérations d’API Web se composent de requêtes et de réponses HTTP. Cet article fournit des exemples d’opérations de lecture, de méthodes, d’URI et l’exemple de JSON que vous pouvez utiliser dans la requête HTTP.

Conditions préalables

• Votre version de portail doit être 9.4.1.x ou supérieure.

• Activer la table et le champ pour les opérations de l’API Web. Pour plus d’informations :Paramètres du site pour l’API Web

• L’API Web des portails accède aux enregistrements de table et suit les autorisations de table accordées aux utilisateurs via les rôles Web associés. Assurez-vous de configurer les autorisations de table appropriées. Plus d’informations : Créer des rôles Web

Enregistrements de requête

L’exemple suivant interroge les enregistrements de compte :

Exemple de réponse

{
"value": [
    {
    "@odata.etag": "W/\"1066412\"",
    "name": "Fourth Coffee (sample)",
    "accountid": "d2e11ba8-92f6-eb11-94ef-000d3a5aa607"
    },
    {
    "@odata.etag": "W/\"1066413\"",
    "name": "Litware, Inc. (sample)",
    "accountid": "d4e11ba8-92f6-eb11-94ef-000d3a5aa607"
    }
]
}

Utilisez les options de requête système $select et $top pour renvoyer la propriété name pour les trois premiers comptes :

Récupérer le compte en utilisant l’ID de compte :

Exemple de réponse

{
    "@odata.etag": "W/\"1066414\"",
    "name": "Adventure Works (sample)",
    "accountid": "d6e11ba8-92f6-eb11-94ef-000d3a5aa607"
}

Appliquer des options de requête système

Chacune des options de requête système que vous ajoutez à l’URL de l’ensemble d’entités est ajoutée à la syntaxe des chaînes de requête. La première est ajoutée après [?] et les options de requête suivantes sont séparées à l’aide d’un [&]. Toutes les options de requête respectent la casse comme illustré dans l’exemple suivant :

Propriétés spécifiques de la demande

Utilisez l’option de requête système $select pour limiter les propriétés renvoyées comme illustré dans l’exemple suivant :

Filtrer les résultats

Utilisez l’option de requête système $filter pour définir les critères pour lesquels les lignes sont renvoyées.

Opérateurs de filtre standard

L’API Web prend en charge les opérateurs de filtre OData standard répertoriées dans le tableau suivant :

Fonctionnalités de requête standard

L’API Web prend en charge ces fonctions de requête de chaîne OData standard :

Fonctions de requête Dataverse

L’API Web prend en charge les fonctions de requête Dataverse pour filtrer les résultats. Pour plus d’informations, voir Référence de fonction de requête de l’API Web.

Classer les résultats

Spécifiez l’ordre dans lequel les éléments sont renvoyés à l’aide de l’option de requête système $orderby . Utilisez le suffixe asc ou desc pour spécifier l’ordre croissant ou décroissant respectivement. La valeur par défaut est croissant si le suffixe n’est pas appliqué. L’exemple suivant présente la récupération des propriétés de nom et de revenu des comptes contrôlées par le revenu croissant et par le nom décroissant.

Agréger et regrouper les résultats

En utilisant  $apply , vous pouvez agréger et regrouper vos données de manière dynamique comme le montrent les exemples suivants :

Récupérer un nombre de lignes

Utilisez l’option de requête système $count contenant une valeur True pour inclure un nombre d’entités correspondant aux critères de filtre jusqu’à 5 000.

Exemple de réponse

{
"@odata.count": 10,
"value": [
    {
    "@odata.etag": "W/\"1066412\"",
    "name": "Fourth Coffee (sample)",
    "accountid": "d2e11ba8-92f6-eb11-94ef-000d3a5aa607"
    },
    {
    "@odata.etag": "W/\"1066413\"",
    "name": "Litware, Inc. (sample)",
    "accountid": "d4e11ba8-92f6-eb11-94ef-000d3a5aa607"
    },
    {
    "@odata.etag": "W/\"1066414\"",
    "name": "Adventure Works (sample)",
    "accountid": "d6e11ba8-92f6-eb11-94ef-000d3a5aa607"
    }
]
}

Si vous ne souhaitez renvoyer aucune donnée sauf le nombre, vous pouvez appliquer $count à un ensemble pour obtenir uniquement la valeur.

Exemple de réponse

3

Comparaison de colonnes

L’exemple suivant montre comment comparer des colonnes à l’aide de l’API Web :

Extraire des enregistrements de table associés avec une requête

Utilisez l’option de requête système $expand dans les propriétés de navigation pour contrôler quelles données des entités associées sont renvoyées.

Propriété de navigation associée à la recherche

Vous devrez utiliser Microsoft.Dynamics.CRM.associatednavigationproperty comme attribut de recherche lors de l’utilisation de l’option de requête $expand.

Pour déterminer la propriété Microsoft.Dynamics.CRM.associatednavigationproperty d’un attribut, vous pouvez créer la requête GET http suivante pour la colonne en utilisant la convention d’affectation de noms suivante : _name_value.

Dans l’exemple suivant, nous pouvons déterminer la propriété de navigation associée de la colonne Contact principal de la table Compte table en spécifiant le nom de la colonne primarycontactid lors du formatage du nom dans la requête : _primarycontactid_value.

Exemple de réponse

{
"value": [
    {
        "@odata.etag": "W/\"2465216\"",
        "_primarycontactid_value@OData.Community.Display.V1.FormattedValue": "Yvonne McKay (sample)",
        "_primarycontactid_value@Microsoft.Dynamics.CRM.associatednavigationproperty": "primarycontactid",
        "_primarycontactid_value@Microsoft.Dynamics.CRM.lookuplogicalname": "contact",
        "_primarycontactid_value": "417319b5-cd18-ed11-b83c-000d3af4d812",
        "accountid": "2d7319b5-cd18-ed11-b83c-000d3af4d812"
    }
]
}

Nous voyons dans la réponse que la propriété de navigation associée est primarycontactid. La propriété de navigation associée peut être le nom logique ou le nom de schéma de la colonne de recherche selon la façon dont la table a été créée.

Pour plus d’informations, consultez Extraire les données sur les propriétés de recherche.

Extraire les enregistrements de tables associés en développant des propriétés de navigation à valeur unique

L’exemple suivant montre comment récupérer le contact pour tous les enregistrements de compte. Pour les enregistrements de contact associés, nous récupérons uniquement contactid et fullname.

Exemple de réponse

{
"value": [
    {
    "@odata.etag": "W/\"1066412\"",
    "name": "Fourth Coffee (sample)",
    "accountid": "d2e11ba8-92f6-eb11-94ef-000d3a5aa607",
        "primarycontactid": {
        "contactid": "e6e11ba8-92f6-eb11-94ef-000d3a5aa607",
        "fullname": "Yvonne McKay (sample)"
        }
    },
    {
    "@odata.etag": "W/\"1066413\"",
    "name": "Litware, Inc. (sample)",
    "accountid": "d4e11ba8-92f6-eb11-94ef-000d3a5aa607",
        "primarycontactid": {
        "contactid": "e8e11ba8-92f6-eb11-94ef-000d3a5aa607",
        "fullname": "Susanna Stubberod (sample)"
        }
    }
]
}

Extraire les tables associées en développant des propriétés de navigation à valeur de collection

Si vous développez les paramètres de navigation à valeur de collection pour récupérer les tables associées pour les ensembles d’entités, un seul niveau de profondeur est renvoyé s’il y a des données. Sinon, la collection renverra un tableau vide.

Récupérez les tables associées pour une instance d’entité en développant les propriétés de navigation à valeur unique ou à valeur de collection

L’exemple suivant montre comment vous pouvez développer les entités associées pour des groupes d’entités en utilisant les propriétés de navigation à valeur unique ou à valeur de collection. Vous devrez spécifier le nom de la relation de la table dans la syntaxe de votre code.

Étape suivante

Opérations d’écriture, de mise à jour et de suppression à l’aide de l’API Web

Voir aussi

Vue d’ensemble des portails Web API
Didacticiel : Utiliser l’API web des portails
Configurer les autorisations de colonne