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

  • Article

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. accounts est le nom défini de l’entité pour account EntityType. 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
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 enregistrement d’entité, vous devez identifier le nom du jeu d’entités, les noms et les types de propriété valides. Pour toutes les tables et attributs système (colonnes de table), vous pouvez trouver ces informations dans l’article consacré à cette entité dans la section Référence du type d’entité de l’API web. Pour les tables ou colonnes personnalisées, consultez la définition de la table dans le document de $metadata CSDL. Pour plus d’informations : EntityTypes de l’API web

Définition de la valeur de la clé primaire

Chaque table possède une colonne de clé primaire d’identificateur unique que vous pouvez spécifier lors de la création d’une ligne. Dans la plupart des cas, vous devez laisser le système définir cela pour vous, car les valeurs générées par le système sont optimisées pour des performances optimales.

Avec les tables élastiques, vous pouvez créer des enregistrements avec des valeurs de clé primaire en double et différentes valeurs partitionid. Cependant, ce modèle n’est pas compatible avec le modèle piloté ou le canevas Power Apps. En savoir plus sur la définition de la valeur de la clé primaire avec des tables élastiques

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.

$expand imbriqués sur les propriétés de navigation à valeur de collection ne renverront pas de données quand utilisés avec la préférence return=representation. Pour plus d’informations, consultez $expand imbriqué dans les propriétés de navigation à valeur de collection

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

Réponse :


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

Créer plusieurs enregistrements dans une seule requête

La façon la plus rapide de créer plusieurs enregistrements du même type dans une seule requête consiste à utiliser l’action CreateMultiple. Au moment d’écrire ces lignes, l’action CreateMultiple. Toutes les tables standard ne prennent pas en charge cette action, contrairement aux tables élastiques.

Pour plus d’informations :

Avec les tables standard, 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 modèle 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 atomique combinée. Une opération atomique réussit ou échoue entièrement.

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 enregistrements 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 en tant qu’objet dans un tableau défini sur la valeur d’une propriété de navigation à valeur de collection opportunity_customer_accounts.

  • Une tâche est créée car elle est définie en tant qu’objet dans un tableau défini sur la valeur d’une propriété de navigation à valeur de collection Opportunity_Tasks.

Notes

Lorsque vous créez une ligne de table, vous ne pouvez pas insérer d’image non principale en simultané. Pour ajouter une image secondaire, la ligne doit déjà exister.

Demande :

POST [Organization URI]/api/data/v9.0/accounts
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" }
      ]
  }
 ]
}

Réponse :


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 nouveaux enregistrements à des enregistrements existants lors de leur création, utilisez l’annotation @odata.bind pour définir la valeur des propriétés de navigation.

Le corps de la demande suivant publié dans l’ensemble d’entités accounts crée 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.

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

Réponse :


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. Pour activer la détection des doublons, incluez 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 les conditions suivantes sont remplies :

  • L’organisation a activé la détection des doublons.
  • L’entité est activée pour la détection des doublons.
  • Les règles de détection des doublons actives ne sont pas appliquées.

Pour plus d’informations :

Créer un enregistrement depuis un autre enregistrement

Utilisez la fonction InitializeFrom 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 :

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

La création d’un enregistrement à partir d’un autre enregistrement est un processus en deux étapes. Tout d’abord, utilisez la fonction InitializeFrom pour renvoyer les valeurs de propriété mappées à partir de l’enregistrement d’origine. Puis, combinez 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

Demande :

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'
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 suivant :

POST [Organization URI]/api/data/v9.0/accounts
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’enregistrements pour les tables élastiques, 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’informations : Créer un enregistrement dans une table élastique

Voir aussi

Exemple d’opérations de base de l’API web (C#)
Exemple d’opérations de base de l’API web (Javascript côté client)
Fonction InitializeFrom
Effectuer des opérations à l’aide de l’API Web
Composer des demandes HTTP et traiter les erreurs
Interroger les données à l’aide de l’API web
Récupérer une ligne de table à l’aide de l’API web
Mettre à jour et supprimer des lignes de table à l’aide de l’API web
Associer et dissocier des lignes de tables à l’aide de l’API web
Utiliser des fonctions API web
Utiliser des actions API web
Exécuter des opérations par lots à l’aide de l’API Web
Emprunter l’identité d’un autre utilisateur à l’aide de l’API Web
Effectuer les opérations conditionnelles à l’aide de l’API Web

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