Partager via

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

Important

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

Lorsque vous sélectionnez des colonnes à l’aide d’OData dans des requêtes d’API Web Dataverse, utilisez l’option $selectde requête pour choisir les colonnes à retourner. Dans OData, chaque colonne est représentée en tant que propriété. Si vous n’incluez pas d’option $select de requête, la requête retourne toutes les propriétés, ce qui peut réduire les performances.

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 propriété de clé primaire est toujours retournée. Vous n’avez donc pas besoin de l’inclure dans votre $select. Dans cet exemple, accountid est la clé primaire.

Vous pouvez voir d’autres valeurs de propriété 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 ?

Vous trouverez toutes les propriétés disponibles pour une entité dans le document de service $metadata. Pour plus d’informations, consultez Propriétés de l’API web.

Conseil / Astuce

Pour découvrir rapidement les propriétés disponibles, envoyez une requête à l’aide de l’option $top de requête avec une valeur de 1 sans utiliser $select. Par exemple GET [Organization URI]/api/data/v9.2/accounts?$top=1

Web API Entity Type Reference décrit les types d’entités inclus dans Dataverse.

Valeurs mises en forme

Le serveur génère des valeurs mises en forme en tant que valeurs de chaîne 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 Prefer request 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 plus d’informations, consultez Annotations de demande.

La valeur mise en forme est retournée avec l’enregistrement à l’aide d’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 possèdent. Le système stocke les données de propriété 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

Prefer: odata.include-annotations="*" Vous pouvez également inclure toutes les annotations. Pour plus d’informations, consultez Annotations de demande.

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. En utilisant la valeur $expand dans une autre requête, vous pouvez 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.

Actuellement, vous ne pouvez pas spécifier d’alias de colonne à l’aide de l’API Web Dataverse avec OData. OData 4.0 n’inclut pas l’option de requête système $compute introduite dans OData 4.01 requise pour fournir cette fonctionnalité.

Étapes suivantes

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

Joindre des tables

  • Last updated on