Partager via

Sélectionner des colonnes à l’aide d’OData

Important

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

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

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

Requête :

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 la réponse. Dans ce cas, la _transactioncurrencyid_valuepropriété de recherche pour la table/entité de référence Devise (TransactionCurrency) associée est incluse parce querevenue est une propriété de devise.

Quelles propriétés sont 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 dans Dataverse sont décrits dans le Web API Entity Type Reference.

Conseil / Astuce

Le moyen le plus simple de découvrir rapidement les propriétés disponibles consiste à envoyer une requête à l’aide de l’option $top de requête avec une valeur de 1 sans utiliser $select.

Valeurs mises en forme

Les valeurs mises en forme sont des valeurs de chaîne 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
  • Valeurs de date mises en forme dans le fuseau horaire de l’utilisateur

Pour inclure des valeurs mises en forme 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 plusieurs annotations que vous pouvez demander. Permet Prefer: odata.include-annotations="*" d’inclure toutes les annotations. Pour pus d’informations, voir : Demander des annotations

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

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

Par exemple:

Requête :

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"

Le tableau suivant décrit les valeurs et les valeurs mises en forme retournées pour les propriétés demandées.

Propriété Valeur Valeur mise en forme
name Litware, Inc. (sample) Aucun
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 Aucun

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"
        }
    ]
}

Rechercher des données immobilières

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

Par exemple, de nombreuses tables ont des enregistrements que les utilisateurs ou les équipes peuvent posséder. 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 pour obtenir cette valeur, mais vous ne pouvez pas utiliser $select. Toutefois, vous pouvez utiliser $select pour obtenir la propriété de recherche correspondante _ownerid_value .

Lorsque vous incluez la _ownerid_value propriété de recherche avec votre $select, elle retourne 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 Prefer request 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 / Astuce

Vous pouvez également utiliser Prefer: odata.include-annotations="*" pour inclure toutes les annotations. Pour pus d’informations, voir : Demander des annotations

Requête :

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 retourne deux enregistrements de compte différents. L'annotation _ownerid_value@Microsoft.Dynamics.CRM.lookuplogicalname vous indique qu'un team possède la première, et qu'un systemuser possède la seconde.

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 associée.
  • <lookup property name>@Microsoft.Dynamics.CRM.associatednavigationproperty est le nom de la propriété de navigation à valeur unique correspondante. Vous pouvez utiliser $expand cette valeur dans une autre requête pour obtenir plus de données à partir de l’enregistrement associé.

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 colonne à l’aide de l’API Web Dataverse à l’aide d’OData. OData 4.0 n’inclut pas l’option de requête système $compute introduite dans OData 4.01 qui est nécessaire pour fournir cette fonctionnalité.

Étapes suivantes

Découvrez comment associer des tables de données.

Joindre des tables

  • Last updated on