Créer une ligne de table à l’aide de l’API web

Article
07/05/2022
3 minutes de lecture

Notes

Vous n’êtes pas sûr de l’entité par rapport à la table ? Voir Développeurs : Comprendre la terminologie dans Microsoft Dataverse.

Utilisez une requête POST pour envoyer des données pour créer une ligne de table (enregistrement d’entité). Vous pouvez créer plusieurs lignes de table liées en une seule opération en utilisant une insertion profonde. Vous devez également savoir comment définir des valeurs pour associer une nouvelle ligne de table aux tables existantes à l’aide de l’annotation @odata.bind.

Notes

Pour plus d’informations sur la création et la mise à jour des définitions de table (entité) à l’aide de l’API web, consultez Créer et mettre à jour des définitions de table à l’aide de l’API web.

Création de base

Cet exemple crée un nouvel enregistrement d’entité de compte. L’en-tête OData-EntityId de réponse contient l’URI de l’entité créée.

Demande


POST [Organization URI]/api/data/v9.0/accounts HTTP/1.1
Content-Type: application/json; charset=utf-8
OData-MaxVersion: 4.0
OData-Version: 4.0
Accept: application/json

{
    "name": "Sample Account",
    "creditonhold": false,
    "address1_latitude": 47.639583,
    "description": "This is the description of the sample account",
    "revenue": 5000000,
    "accountcategorycode": 1
}

Réponse


HTTP/1.1 204 No Content
OData-Version: 4.0
OData-EntityId: [Organization URI]/api/data/v9.0/accounts(7eb682f1-ca75-e511-80d4-00155d2a68d1)

Pour créer un nouvel enregistrement d’entité, vous devez identifier les noms et les types de propriété valides. Pour toutes les entités et attributs système (colonnes de table), vous pouvez trouver ces informations dans la rubrique consacrée à cette entité dans la section A propos de la référence de table. Pour les entités ou attributs personnalisés, consultez la définition de l’entité dans le document de $métadonnées CSDL. Pour plus d’informations : EntityTypes de l’API web

Créer une entité avec les données retournées

Vous pouvez composer votre demande POST de sorte que les données de l’enregistrement créé soient retournées avec le statut 201 (Created). Pour obtenir ce résultat, vous devez utiliser la préférence return=representation dans les en-têtes de demande.

Pour contrôler les propriétés retournées, ajoutez l’option de requête $select à l’URL de l’ensemble d’entités. Vous pouvez également utiliser $expand pour renvoyer les entités associées.

Lorsqu’une entité est créée de cette manière, l’en-tête OData-EntityId contenant l’URI de l’enregistrement créé n’est pas retourné.

Cet exemple crée une entité Compte et retourne les données demandées dans la réponse.

Demande


POST [Organization URI]/api/data/v9.0/accounts?$select=name,creditonhold,address1_latitude,description,revenue,accountcategorycode,createdon HTTP/1.1
OData-MaxVersion: 4.0
OData-Version: 4.0
Accept: application/json
Content-Type: application/json; charset=utf-8
Prefer: return=representation

{
   "name": "Sample Account",
   "creditonhold": false,
   "address1_latitude": 47.639583,
   "description": "This is the description of the sample account",
   "revenue": 5000000,
   "accountcategorycode": 1
}

Response


HTTP/1.1 201 Created
Content-Type: application/json; odata.metadata=minimal
Preference-Applied: return=representation
OData-Version: 4.0

{
    "@odata.context": "[Organization URI]/api/data/v9.0/$metadata#accounts/$entity",
    "@odata.etag": "W/\"536530\"",
    "accountid": "d6f193fc-ce85-e611-80d8-00155d2a68de",
    "accountcategorycode": 1,
    "description": "This is the description of the sample account",
    "address1_latitude": 47.63958,
    "creditonhold": false,
    "name": "Sample Account",
    "createdon": "2016-09-28T22:57:53Z",
    "revenue": 5000000.0000,
    "_transactioncurrencyid_value": "048dddaa-6f7f-e611-80d3-00155db5e0b6"
}

Vous pouvez créer des entités associées entre elles en les définissant comme des valeurs de propriétés de navigation. Ce processus s’appelle l’insertion profonde. Cette approche a deux avantages. Elle est plus efficace, en remplaçant plusieurs opérations de création et d’association plus simples par une opération combinée. En outre, elle est atomique, car soit l’opération entière aboutit et tous les objets associés sont créés, soit l’opération échoue et aucun n’est créé.

Tout comme la création de base, l’en-tête OData-EntityId de réponse contient l’URI de l’entité créée. Les URI pour les entités associées créées ne sont pas retournées. Vous pouvez obtenir les valeurs de clé primaire des enregistrements si vous utilisez l’en-tête Prefer: return=representation afin qu’il renvoie les valeurs de l’enregistrement créé. Plus d’information : Créer avec des données renvoyées

Par exemple, le corps de demande suivant publié dans l’ensemble d’entités accounts crée un total de quatre nouvelles entités dans le contexte de création d’un compte.

Un contact est créé car il est défini en tant que propriété d’objet de la propriété de navigation à valeur unique primarycontactid.
Une opportunité est créée car elle est définie dans un objet dans un tableau qui a la valeur d’une propriété de navigation avec une valeur de collection opportunity_customer_accounts.
Une tâche est créée car elle est définie dans un objet dans un tableau qui a la valeur d’une propriété de navigation avec une valeur de collection Opportunity_Tasks.

Notes

Lors de la création d′une ligne de table, il est impossible de combiner la création de ligne avec l′insertion d′une image secondaire. Pour ajouter une image secondaire, la ligne doit déjà exister.

Demande

POST [Organization URI]/api/data/v9.0/accounts HTTP/1.1
Content-Type: application/json; charset=utf-8
OData-MaxVersion: 4.0
OData-Version: 4.0
Accept: application/json

{
 "name": "Sample Account",
 "primarycontactid":
 {
     "firstname": "John",
     "lastname": "Smith"
 },
 "opportunity_customer_accounts":
 [
  {
      "name": "Opportunity associated to Sample Account",
      "Opportunity_Tasks":
      [
       { "subject": "Task associated to opportunity" }
      ]
  }
 ]
}

Response


HTTP/1.1 204 No Content
OData-Version: 4.0
OData-EntityId: [Organization URI]/api/data/v9.0/accounts(3c6e4b5f-86f6-e411-80dd-00155d2a68cb)

Associer des lignes de table lors de la création

Pour associer de nouvelles entités aux entités existantes lorsqu’elles sont créées, vous devez définir la valeur des propriétés de navigation à l’aide de l’annotation @odata.bind.

Le corps de la demande suivant publié dans l’ensemble d’entités accounts créera un nouveau compte associé à un contact existant avec la valeur contactid de 00000000-0000-0000-0000-000000000001 et deux tâches existantes avec les valeurs activityid de 00000000-0000-0000-0000-000000000002 et 00000000-0000-0000-0000-000000000003.

Notes

Cette demande utilise l’en-tête Prefer: return=representation afin qu’il renvoie les valeurs de l’enregistrement créé. Plus d’information : Créer avec des données renvoyées

Demande


POST [Organization URI]/api/data/v9.0/accounts?$select=name&$expand=primarycontactid($select=fullname),Account_Tasks($select=subject) HTTP/1.1
Content-Type: application/json; charset=utf-8
OData-MaxVersion: 4.0
OData-Version: 4.0
Accept: application/json
Prefer: return=representation

{
    "name": "Sample Account",
    "primarycontactid@odata.bind": "/contacts(00000000-0000-0000-0000-000000000001)",
    "Account_Tasks@odata.bind": [
        "/tasks(00000000-0000-0000-0000-000000000002)",
        "/tasks(00000000-0000-0000-0000-000000000003)"
    ]
}

Response


HTTP/1.1 201 Created
OData-Version: 4.0
Preference-Applied: return=representation

{
    "@odata.context": "[Organization URI]/api/data/v9.1/$metadata#accounts(name,primarycontactid(fullname),Account_Tasks(subject))/$entity",
    "@odata.etag": "W/\"36236432\"",
    "name": "Sample Account",
    "accountid": "00000000-0000-0000-0000-000000000004",
    "primarycontactid": {
        "@odata.etag": "W/\"28877094\"",
        "fullname": "Yvonne McKay (sample)",
        "contactid": "00000000-0000-0000-0000-000000000001"
    },
    "Account_Tasks": [
        {
            "@odata.etag": "W/\"36236437\"",
            "subject": "Task 1",
            "activityid": "00000000-0000-0000-0000-000000000002"
        },
        {
            "@odata.etag": "W/\"36236440\"",
            "subject": "Task 2",
            "activityid": "00000000-0000-0000-0000-000000000003"
        }
    ]
}

Rechercher des enregistrements dupliqués

Par défaut, la détection des doublons est supprimée lorsque vous créez des enregistrements à l’aide de l’API Web. Vous devez inclure l’en-tête MSCRM.SuppressDuplicateDetection: false avec votre demande POST pour activer la détection des doublons. La détection des doublons s’applique uniquement lorsque 1) l’organisation a activé la détection des doublons, 2) l’entité est activée pour la détection des doublons et 3) les règles actives de détection des doublons sont appliquées. Pour plus d’informations : Détecter les données dupliquées avec le code

Consultez Détecter les données dupliquées à l’aide de l’API web pour en savoir plus sur la manière de vérifier les enregistrements dupliqués pendant l’opération de création.

Créez un enregistrement depuis un autre enregistrement

Utilisez InitializeFrom Function pour créer un enregistrement dans le contexte d’un enregistrement existant où un mappage existe pour la relation entre les tables. Pour plus d’informations sur la création de ces mappages, consultez :

Notes

Pour déterminer si deux entités peuvent être mappées, utilisez la requête suivante :
GET [Organization URI]/api/data/v9.1/entitymaps?$select=sourceentityname,targetentityname&$orderby=sourceentityname

Il s’agit d’un processus en deux étapes. La fonction InitializeFrom ne crée pas l’enregistrement, mais elle renvoie des données que vous pouvez utiliser pour créer un enregistrement avec des valeurs de propriété spécifiées mappées à partir de l’enregistrement d’origine. Vous combinerez les données de réponse renvoyées dans la fonction InitializeFrom avec les modifications que vous souhaitez apporter, puis POST les données pour créer l’enregistrement.

L’exemple suivant montre comment créer un enregistrement de compte en utilisant les valeurs d’un enregistrement de compte existant avec une valeur accountid égale à 00000000-0000-0000-0000-000000000001.

Étape 1 : Obtenir les données à l’aide de InitializeFrom

Requête

GET [Organization URI]/api/data/v9.0/InitializeFrom(EntityMoniker=@p1,TargetEntityName=@p2,TargetFieldType=@p3)?@p1={'@odata.id':'accounts(00000000-0000-0000-0000-000000000001)'}&@p2='account'&@p3=Microsoft.Dynamics.CRM.TargetFieldType'ValidForCreate' HTTP/1.1
If-None-Match: null
OData-Version: 4.0
OData-MaxVersion: 4.0
Content-Type: application/json
Accept: application/json

Réponse

{
    "@odata.context": "[Organization URI]/api/data/v9.0/$metadata#accounts/$entity",
    "@odata.type": "#Microsoft.Dynamics.CRM.account",
    "parentaccountid@odata.bind": "accounts(00000000-0000-0000-0000-000000000001)",
    "transactioncurrencyid@odata.bind": "transactioncurrencies(732e87e1-1d96-e711-80e4-00155db75426)",
    "address1_line1": "123 Maple St.",
    "address1_city": "Seattle",
    "address1_country": "United States of America"
}

Étape 2 : Créer l’enregistrement

La réponse reçue de la fonction InitializeFrom comprend les valeurs des colonnes mappées entre la table source et la table cible et le GUID de l’enregistrement parent. Le mappage de colonne entre des tables partageant une relation est différent pour chaque ensemble de tables et est personnalisable. La réponse de la requête de fonction InitializeFrom peut donc varier pour différentes organisations.

D’autres valeurs de propriété peuvent également être définies et/ou modifiées pour le nouvel enregistrement en les ajoutant dans le corps de la requête JSON, comme illustré dans l’exemple ci-dessous.

POST [Organization URI]/api/data/v9.0/accounts HTTP/1.1
Content-Type: application/json; charset=utf-8
OData-MaxVersion: 4.0
OData-Version: 4.0
Accept: application/json

    {
        "@odata.context": "[Organization URI]/api/data/v9.0/$metadata#accounts/$entity",
        "@odata.type": "#Microsoft.Dynamics.CRM.account",
        "parentaccountid@odata.bind": "accounts(00000000-0000-0000-0000-000000000001)",
        "transactioncurrencyid@odata.bind": "transactioncurrencies(732e87e1-1d96-e711-80e4-00155db75426)",
        "name":"Contoso Ltd",
        "numberofemployees":"200",
        "address1_line1":"100 Maple St.",
        "address1_city":"Seattle",
        "address1_country":"United States of America",
        "fax":"73737"
    }
}

Créer des documents dans des partitions de stockage

Si vous créez un grand nombre d’entités contenant des documents, vous pouvez créer les entités dans les partitions de stockage pour accélérer l’accès à ces enregistrements d’entité.

Plus d’information : Accéder plus rapidement aux documents à l’aide de partitions de stockage

Voir aussi

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

Créer une ligne de table à l’aide de l’API web

Création de base

Créer une entité avec les données retournées

Créer des lignes de table associées en une seule opération

Associer des lignes de table lors de la création

Rechercher des enregistrements dupliqués

Créez un enregistrement depuis un autre enregistrement

Étape 1 : Obtenir les données à l’aide de InitializeFrom

Étape 2 : Créer l’enregistrement

Créer des documents dans des partitions de stockage

Voir aussi

Commentaires