Partage via

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

  • Article

Notes

À compter du 12 octobre 2022, le portail Power Apps devient Power Pages. Plus d’informations : Microsoft Power Pages est maintenant généralement disponible (blog)
Nous allons bientôt migrer et fusionner la documentation des portails Power Apps avec la documentation de Power Pages.

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

Notes

Lorsqu’on se réfère aux tables Dataverse à l’aide de l’API Web des portails, vous devez utiliser EntitySetName, par exemple, pour accéder à la table compte, la syntaxe du code utilisera le nom EntitySetName de comptes.

Enregistrements de requête

L’exemple suivant interroge les enregistrements de compte :

Opération Method URI
Récupérer des enregistrements de table GET [Portal URI]/_api/accounts

Exemple :
 https://contoso.powerappsportals.com/_api/accounts

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 :

Opération Method URI
Récupérer les trois premiers enregistrements d’entité GET [Portal URI]/_api/accounts?$select=name,revenue&$top=3

Exemple :
https://contoso.powerappsportals.com/_api/accounts?$select=name,revenue&$top=3

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

Opération Method URI
Récupérer une propriété spécifique pour un enregistrement GET [Portal URI]/_api/accounts(e0e11ba8-92f6-eb11-94ef-000d3a5aa607)?$select=name

Exemple :
https://contoso.powerappsportals.com/_api/accounts(e0e11ba8-92f6-eb11-94ef-000d3a5aa607)?$select=name

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 :

Method URI
GET [Portal URI]/_api/accounts?$select=name,revenue&$filter=revenue gt 90000&$top=3

Exemple :
https://contoso.powerappsportals.com/_api/accounts?$select=name,revenue&$filter=revenue gt 90000&$top=3

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 :

Method URI
GET [Portal URI]/_api/accounts?$select=name,revenue&$top=3

Exemple :
https://contoso.powerappsportals.com/_api/accounts?$select=name,revenue&$top=3

Important

C’est une pratique recommandée. Si les propriétés ne sont pas spécifiées et que vous avez configuré la valeur du paramètre de site Webapi/<table name>/fields dans *, alors toutes les propriétés seront renvoyées en utilisant $select. Si aucune propriété n’est spécifiée, une erreur sera renvoyée.

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 :

Opérateur Description Exemple
Opérateurs de comparaison
eq Égal à $filter=revenue eq 100000
ne Différent de $filter=revenue ne 100000
gt Supérieur(e) à $filter=revenue gt 100000
ge Supérieur ou égal à $filter=revenue ge 100000
lt Inférieur(e) à $filter=revenue lt 100000
le Inférieur ou égal à $filter=revenue le 100000
Opérateurs logiques
and ET logique $filter=revenue lt 100000 and revenue gt 2000
or OU logique $filter=contains(name,’(sample)’) or contains(name,’test’)
not Négation logique $filter=not contains(name,’sample’)
Opérateurs de groupement
( ) Groupement de priorité (contains(name,’sample’) or contains(name,’test’)) and revenue gt 5000

Fonctionnalités de requête standard

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

Fonction Exemple
contient $filter=contains(name,’(sample)’)
endswith $filter=endswith(name,’Inc.’)
startswith $filter=startswith(name,’a’)

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.

Method URI
GET [Portal URI]/_api/accounts?$select=name,revenue&$orderby=name asc,revenue desc&$filter=revenue gt 90000

Exemple :
https://contoso.powerappsportals.com/_api/accounts?$select=name,revenue&$orderby=name asc,revenue desc&$filter=revenue gt 90000

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 :

Scénarios Exemple
Liste de statuts uniques dans la requête accounts?$apply=groupby((statuscode))
Somme agrégée de la valeur estimée opportunities?$apply=aggregate(estimatedvalue with sum as total)
Taille moyenne de la transaction basée sur la valeur et le statut estimés opportunities?$apply=groupby((statuscode),aggregate(estimatedvalue with average as averagevalue)
Somme de la valeur estimée selon le statut opportunities?$apply=groupby((statuscode),aggregate(estimatedvalue with sum as total))
Revenu total d’opportunités par nom de compte opportunities?$apply=groupby((parentaccountid/name),aggregate(estimatedvalue with sum as total))
Noms du contact principal pour les comptes dans « WA » accounts?$apply=filter(address1_stateorprovince eq ’WA’)/groupby((primarycontactid/fullname))
Date et heure de l’enregistrement créé en dernier accounts?$apply=aggregate(createdon with max as lastCreate)
Date et heure de l’enregistrement créé en premier accounts?$apply=aggregate(createdon with min as firstCreate)

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.

Method URI
GET [Portal URI/_api/accounts?$select=name&$filter=contains(name,'sample')&$count=true

Exemple :
https://contoso.powerappsportals.com/_api/accounts?$select=name&$filter=contains(name,'sample')&$count=true

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.

Method URI
GET [Portal URI/_api/accounts/$count

Exemple :
https://contoso.powerappsportals.com/_api/accounts/$count

Exemple de réponse

3

Comparaison de colonnes

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

Method URI
OBTENIR [Portal URI]/_api/contacts?$select=firstname&$filter=firstname eq lastname

Exemple :
https://contoso.powerappsportals.com/_api/contacts?$select=firstname&$filter=firstname eq lastname

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.

Method URI
OBTENIR [Portal URI]/_api/accounts?$select=_primarycontactid_value

Exemple
https://contoso.powerappsportals.com/_api/accounts?$select=_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.

Method URI
OBTENIR [Portal URI]/_api/accounts?$select=name&$expand=primarycontactid($select=contactid,fullname)

Exemple :
https://contoso.powerappsportals.com/_api/accounts?$select=name&$expand=primarycontactid($select=contactid,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.

Method URI
GET [Portal URI]/_api/accounts?$top=5&$select=name&$expand=Account_Tasks($select=subject,scheduledstart)

Exemple :
https://contoso.powerappsportals.com/_api/accounts?$top=5&$select=name&$expand=Account_Tasks($select=subject,scheduledstart)

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.

Method URI
GET [Portal URI]/_api/accounts?$top=5&$select=name&$expand=primarycontactid($select=contactid,fullname),Account_Tasks($select=subject,scheduledstart)

Exemple :
https://contoso.powerappsportals.com/_api/accounts?$top=5&$select=name&$expand=primarycontactid($select=contactid,fullname),Account_Tasks($select=subject,scheduledstart)

É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

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é).