Partager via

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

Envoyez une POST demande à la ressource entityset d’API web pour créer une ligne de table (enregistrement d’entité) dans Microsoft Dataverse. Vous pouvez créer plusieurs lignes de table associées dans une seule opération à l’aide d’une insertion approfondie. Vous devez également savoir comment définir des valeurs pour associer une nouvelle ligne de table à des tables existantes à l’aide de l’annotation @odata.bind .

Remarque

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 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.2/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.2/accounts(00aa00aa-bb11-cc22-dd33-44ee44ee44ee)

Pour créer un enregistrement, vous devez identifier le nom du jeu d’entités valide, les noms de propriétés et les types.

Remarque

Dans Power Apps, lors de l’affichage d’une liste de tables, sélectionnez Avancé>Outils. Sélectionnez Copier le nom de l’ensemble pour copier le nom de l’ensemble d’entités pour la table.

Vous pouvez également sélectionner Lien API vers les données de la table pour afficher les 10 premières lignes de données dans votre navigateur. Cette fonctionnalité fonctionne mieux lorsque vous avez une extension de navigateur telle que le formateur JSON installé qui met en forme les données de texte JSON retournées.

Le nom de l’ensemble d’entités n’est pas toujours le même que le nom de la collection ou le nom au pluriel de la table. Elle est stockée dans une propriété distincte appelée EntitySetName.

Lorsque vous créez une ligne de table, vous ne pouvez pas insérer d’image non principale en simultané. Pour ajouter une image non primaire, la ligne doit déjà exister. En savoir plus sur les images principales.

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. Plus d’informations : EntityTypes de l’API web.

Définition de la valeur de la clé primaire

Chaque table a 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 autoriser le système à définir cette valeur pour vous, car les valeurs générées par le système sont optimisées pour des performances optimales.

Dataverse stocke les données de clé primaire dans la télémétrie pour aider à maintenir le service. Si vous spécifiez des valeurs de clé primaire personnalisées, n’utilisez pas d’informations sensibles dans ces valeurs.

En utilisant des tables élastiques, vous pouvez créer des enregistrements avec des valeurs de clé primaire en double et des valeurs partitionid différentes. Toutefois, ce modèle n’est pas compatible avec Power Apps pilotée par modèle ou de type canevas. Découvrez comment définir la valeur de clé primaire avec des tables élastiques.

Créer avec les données retournées

Vous pouvez composer votre POST demande afin qu’elle retourne des données à partir de l’enregistrement créé avec l’état 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 $select de requête à l’URL du jeu d’entités. Vous pouvez également utiliser $expand pour retourner des entités associées.

L'imbrication de $expand sur les propriétés de navigation à valeur de collection ne retourne pas de données lorsqu'elle est utilisée avec la préférence return=representation. Pour plus d’informations, consultez les $expand imbriqués sur les propriétés de navigation à valeur de collection.

Lorsque vous créez une entité à l’aide de cette méthode, l’en-tête OData-EntityId contenant l’URI de l’enregistrement créé n’est pas retourné.

L’exemple suivant crée une entité de compte et retourne les données demandées dans la réponse.

Demande :


POST [Organization URI]/api/data/v9.2/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.2/$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

Pour créer rapidement plusieurs enregistrements du même type dans une requête unique, utilisez l’action CreateMultiple. Au moment de cette écriture, l’action CreateMultiple n’est pas prise en charge par toutes les tables standard, mais toutes les tables élastiques la prennent en charge.

Pour en savoir plus, consultez :

En utilisant des tables standard, vous pouvez créer des entités qui se rapportent les unes aux autres en les définissant comme valeurs de propriété de navigation. Ce modèle s’appelle l’insertion profonde. Cette approche a deux avantages. Il est plus efficace, car il remplace 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 lors d'une 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 à l’aide de l’en-tête Prefer: return=representation afin qu’elle retourne les valeurs de l’enregistrement créé. En savoir plus sur la création d’enregistrements avec des données retourné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éé avec firstname et lastname des valeurs, car vous le définissez en tant que propriété d’objet de la propriété de navigation à valeur unique nommée primarycontactid.

  • Une opportunité liée au compte est créée, car vous la définissez en tant qu’objet dans un tableau défini sur la valeur d’une propriété de navigation à valeur de collection nommée opportunity_customer_accounts.

  • Une tâche liée à l’opportunité est créée, car vous la définissez comme un objet dans un tableau assigné à la valeur d’une propriété de navigation de type collection nommée Opportunity_Tasks.

Demande :

POST [Organization URI]/api/data/v9.2/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.2/accounts(11bb11bb-cc22-dd33-ee44-55ff55ff55ff)

Associer des lignes de table lors de la création

Pour associer de nouveaux enregistrements à des enregistrements existants lorsque vous les créez, 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 requête utilise l’en-tête Prefer: return=representation afin qu’elle retourne les valeurs de l’enregistrement créé. Pour plus d’informations, consultez Créer avec les données retournées.

Demande :


POST [Organization URI]/api/data/v9.2/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.2/$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, le système supprime la détection en double lorsque vous créez des enregistrements. Pour activer la détection des doublons, incluez l’en-tête MSCRM.SuppressDuplicateDetection: false avec votre demande POST. 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 sont appliquées.

Pour en savoir plus, consultez :

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.2/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. Ensuite, combinez les données de réponse retournées dans la fonction InitializeFrom avec les modifications que vous souhaitez apporter, et utilisez POST les données pour créer l’enregistrement.

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

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

Demande :

GET [Organization URI]/api/data/v9.2/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.2/$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 que vous recevez de InitializeFrom inclut les valeurs des colonnes mappées entre la table source et la table cible, ainsi que le GUID de l'enregistrement parent. Le mappage de colonnes entre des tables ayant une relation diffère selon les tables et les organisations, donc la réponse de InitializeFrom varie.

Vous pouvez définir ou modifier d’autres valeurs de propriété 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.2/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.2/$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, créez les entités dans les partitions de stockage pour accélérer l’accès à ces enregistrements d’entité.

Découvrez comment créer des enregistrements 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 de l'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

  • Last updated on