Colonnes Sélectionner utilisant OData

Article
08/05/2024

Important

Lorsque vous interrogez des données, il est important de limiter la quantité de données renvoyées pour optimiser les performances. Sélectionnez uniquement les colonnes contenant les données dont vous avez besoin.

Utilisez l’option de requête pour choisir les colonnes à renvoyer avec votre requête. $select ... Dans OData, chaque colonne est représentée comme une propriété . Si vous n’incluez pas d’option de requête $select, toutes les propriétés sont renvoyées.

L’exemple suivant demande les propriétés name et revenue de la première ligne de la ressource accounts EntitySet :

Demande :

GET [Organization URI]/api/data/v9.2/accounts?$select=name,revenue&$top=1
Accept: application/json  
OData-MaxVersion: 4.0  
OData-Version: 4.0

Réponse :

HTTP/1.1 200 OK  
Content-Type: application/json; odata.metadata=minimal  
OData-Version: 4.0  

{
    "@odata.context": "[Organization URI]/api/data/v9.2/$metadata#accounts(name,revenue)",
    "value": [
        {
            "@odata.etag": "W/\"81052965\"",
            "name": "Litware, Inc. (sample)",
            "revenue": 20000.0000,
            "_transactioncurrencyid_value": "228f42f8-e646-e111-8eb7-78e7d162ced1",
            "accountid": "4624eff7-53d3-ed11-a7c7-000d3a993550"
        }
    ]
}

La clé primaire est toujours renvoyée, vous n’avez donc pas besoin de l’inclure dans votre $select. Dans cet exemple, accountid est la clé primaire.

D’autres valeurs de propriété peuvent également être incluses dans le réponse. Dans ce cas, la propriété de recherche pour la référence de table/entité de devise (TransactionCurrency) associée est incluse car il s’agit d’une propriété de devise. _transactioncurrencyid_value ... ... revenue

Quelles sont les propriétés disponibles ?

Toutes les propriétés disponibles pour une entité se trouvent dans le document de service $metadata. Plus d’informations : Propriétés de l’API Web

Les types d’entités inclus avec Dataverse sont décrites dans le Web API Entity Type Reference.

Conseil

La façon la plus simple de découvrir rapidement les propriétés disponibles est d’envoyer une requête en utilisant l’option $top avec une valeur de 1 sans utiliser $select.

Valeurs mises en forme

Les valeurs mises en forme sont des chaînes de caractères générées sur le serveur que vous pouvez utiliser dans votre application. Les valeurs mises en forme sont les suivantes :

Les étiquettes localisées pour les colonnes choix, choix, oui/non, état et raison du statut
Valeur du nom primaire pour les propriétés recherche et propriétaire
Valeurs monétaires avec symboles monétaires
Date mise en forme dans le fuseau horaire de l’utilisateur

Pour inclure des valeurs formatées dans vos résultats, utilisez l’en-tête de requête Prefer pour envoyer la préférence odata.include-annotations

Prefer: odata.include-annotations="OData.Community.Display.V1.FormattedValue"

Les valeurs mises en forme sont l’une des nombreuses annotations que vous pouvez demander. Utilisez Prefer: odata.include-annotations="*" pour inclure toutes les annotations. Plus d’informations : Demander des annotations

La valeur mise en forme est renvoyée avec l’enregistrement avec une annotation qui suit cette convention :

<property name>@OData.Community.Display.V1.FormattedValue

Par exemple :

Demande :

GET [Organization URI]/api/data/v9.2/accounts?$select=name,revenue,_primarycontactid_value,customertypecode,modifiedon
&$top=1
Accept: application/json  
OData-MaxVersion: 4.0  
OData-Version: 4.0
Prefer: odata.include-annotations="OData.Community.Display.V1.FormattedValue"

La table suivante décrit les valeurs et les valeurs formatées qui sont renvoyées pour les propriétés demandées.

Propriété	active	Valeur mise en forme
`name`	`Litware, Inc. (sample)`	None
`revenue`	`20000.0000`	`$20,000.00`
`_primarycontactid_value`	`70bf4d48-34cb-ed11-b596-0022481d68cd`	`Susanna Stubberod (sample)`
`customertypecode`	`1`	`Competitor`
`modifiedon`	`2023-04-07T21:59:01Z`	`4/7/2023 2:59 PM`
`_transactioncurrencyid_value`	`228f42f8-e646-e111-8eb7-78e7d162ced1`	`US Dollar`
`accountid`	`78914942-34cb-ed11-b596-0022481d68cd`	None

Réponse :

HTTP/1.1 200 OK  
Content-Type: application/json; odata.metadata=minimal  
OData-Version: 4.0
Preference-Applied: odata.include-annotations="OData.Community.Display.V1.FormattedValue"

{
    "@odata.context": "[Organization URI]/api/data/v9.2/$metadata#accounts(name,revenue)",
    "value": [
{
            "@odata.etag": "W/\"81359849\"",
            "name": "Litware, Inc. (sample)",
            "revenue@OData.Community.Display.V1.FormattedValue": "$20,000.00",
            "revenue": 20000.0000,
            "_primarycontactid_value@OData.Community.Display.V1.FormattedValue": "Susanna Stubberod (sample)",
            "_primarycontactid_value": "70bf4d48-34cb-ed11-b596-0022481d68cd",
            "customertypecode@OData.Community.Display.V1.FormattedValue": "Competitor",
            "customertypecode": 1,
            "modifiedon@OData.Community.Display.V1.FormattedValue": "4/7/2023 2:59 PM",
            "modifiedon": "2023-04-07T21:59:01Z",
            "_transactioncurrencyid_value@OData.Community.Display.V1.FormattedValue": "US Dollar",
            "_transactioncurrencyid_value": "228f42f8-e646-e111-8eb7-78e7d162ced1",
            "accountid": "78914942-34cb-ed11-b596-0022481d68cd"
        }
    ]
}

Recherche de données sur les propriétés

Lorsqu’une propriété de recherche représente une relation multi-table ou polymorphe, vous devez demander des annotations spécifiques pour déterminer quelle table contient les données associées.

Par exemple, de nombreuses tables contiennent des enregistrements dont les utilisateurs ou les équipes peuvent être propriétaires. Les données de propriété sont stockées dans une colonne de recherche nommée ownerid. Cette colonne est une propriété de navigation à valeur unique dans OData. Vous pouvez utiliser $expand pour créer une jointure afin d’obtenir cette valeur, mais vous ne pouvez pas utiliser $select. Cependant, vous pouvez utiliser $select pour obtenir la propriété de recherche _ownerid_value correspondante.

Lorsque vous incluez la propriété de recherche _ownerid_value avec votre $select, elle renvoie une valeur GUID. Cette valeur ne vous indique pas si le propriétaire de l’enregistrement est un utilisateur ou une équipe. Vous devez demander des annotations pour obtenir ces données.

Pour inclure ces annotations dans vos résultats, utilisez l’en-tête de requête Prefer pour envoyer la préférence odata.include-annotations avec ces paramètres : ... ...

Prefer: odata.include-annotations="Microsoft.Dynamics.CRM.associatednavigationproperty,Microsoft.Dynamics.CRM.lookuplogicalname"

Conseil

Ou vous pouvez utiliser Prefer: odata.include-annotations="*" pour inclure toutes les annotations. Plus d’informations : Demander des annotations

Demande :

GET [Organization URI]/api/data/v9.2/accounts?$select=name,_ownerid_value&$top=2
Accept: application/json  
OData-MaxVersion: 4.0  
OData-Version: 4.0
Prefer: odata.include-annotations="Microsoft.Dynamics.CRM.associatednavigationproperty,Microsoft.Dynamics.CRM.lookuplogicalname"

La réponse suivante renvoie deux enregistrements de compte différents. Le _ownerid_value@Microsoft.Dynamics.CRM.lookuplogicalname annotation vous indique qu’un team possède le premier, et qu’un systemuser possède le second.

Réponse :

HTTP/1.1 200 OK  
Content-Type: application/json; odata.metadata=minimal  
OData-Version: 4.0
Preference-Applied: odata.include-annotations="Microsoft.Dynamics.CRM.associatednavigationproperty,Microsoft.Dynamics.CRM.lookuplogicalname"

{
    "@odata.context": "[Organization URI]/api/data/v9.2/$metadata#accounts(name,_ownerid_value)",
    "value": [
        {
            "@odata.etag": "W/\"81550512\"",
            "name": "Adventure Works (sample)",
            "_ownerid_value@Microsoft.Dynamics.CRM.associatednavigationproperty": "ownerid",
            "_ownerid_value@Microsoft.Dynamics.CRM.lookuplogicalname": "team",
            "_ownerid_value": "39e0dbe4-131b-e111-ba7e-78e7d1620f5e",
            "accountid": "1adef0b8-54d3-ed11-a7c7-000d3a993550"
        },
        {
            "@odata.etag": "W/\"81359849\"",
            "name": "Litware, Inc. (sample)",
            "_ownerid_value@Microsoft.Dynamics.CRM.associatednavigationproperty": "ownerid",
            "_ownerid_value@Microsoft.Dynamics.CRM.lookuplogicalname": "systemuser",
            "_ownerid_value": "4026be43-6b69-e111-8f65-78e7d1620f5e",
            "accountid": "78914942-34cb-ed11-b596-0022481d68cd"
        }
    ]
}

<lookup property name>@Microsoft.Dynamics.CRM.lookuplogicalname est le nom logique de la table liée.
<lookup property name>@Microsoft.Dynamics.CRM.associatednavigationproperty est le nom de la propriété de navigation correspondante à valeur unique. Vous pouvez utiliser $expand avec cette valeur dans une autre requête pour obtenir plus de données de l’enregistrement lié.

Alias de colonne

Pour l’API Web, utilisez fetchxml pour spécifier des alias personnalisés pour les colonnes.

Il n’existe actuellement aucun moyen de spécifier des alias de colonnes à l’aide de l’API Web à l’aide d’OData. Dataverse OData 4.0 n’inclut pas l’option de requête système $compute introduite dans OData 4.01 qui est requise pour fournir cette capacité.

Étapes suivantes

Découvrez comment joindre des tables.

Joindre des tables

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

Partager via

Colonnes Sélectionner utilisant OData

Quelles sont les propriétés disponibles ?

Valeurs mises en forme

Recherche de données sur les propriétés

Alias de colonne

Étapes suivantes

Ressources supplémentaires