Créer une entité à l'aide de l'API Web

Article
10/31/2017

Date de publication : janvier 2017

S’applique à : Dynamics 365 (online), Dynamics 365 (on-premises), Dynamics CRM 2016, Dynamics CRM Online

Utilisez une demande POST pour envoyer des données pour créer une entité. Vous pouvez créer plusieurs entités associées en une opération simple à l'aide de l'« insertion profonde ». Vous devez également savoir comment définir les valeurs pour associer une nouvelle entité aux entités existantes à l'aide de l'annotation @odata.bind.

Notes

Pour savoir comment créer et mettre à jour les métadonnées de l'entité à l'aide de l'API Web, voir Créer et mettre à jour les définitions d'entité à l’aide de l'API Web.

Contenu de la rubrique

Création de base

Créer des entités associées en une opération

Associer des entités lors de la création

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

Création de base

Cet exemple crée une nouvelle entité de compte. L'en-tête OData-EntityId de réponse contient l'URI de l'entité créée.

Demande

POST cc_WebAPI_ServiceURI/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: cc_WebAPI_ServiceURI/accounts(7eb682f1-ca75-e511-80d4-00155d2a68d1)

Pour créer une nouvelle entité, vous devez identifier les noms et les types de propriété valides. Pour toutes les entités et attributs système, vous trouverez ces informations dans la rubrique de cette entité dans Web API EntityType Reference. Pour les entités ou attributs personnalisés, consultez la définition de l'entité dans d80cfb87-d4f1-4c75-bcc8-4f54d1351e26#bkmk_csdl.Pour plus d'informations :d80cfb87-d4f1-4c75-bcc8-4f54d1351e26#bkmk_entityTypes

Créer des entités associées en une opération

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.

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

Par exemple, le corps de demande suivant publié dans l'ensemble d'entités Account 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.

Demande

POST cc_WebAPI_ServiceURI/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" }
      ]
  }
 ]
}

Réponse

HTTP/1.1 204 No Content
OData-Version: 4.0
OData-EntityId: cc_WebAPI_ServiceURI/accounts(3c6e4b5f-86f6-e411-80dd-00155d2a68cb)

Associer des entités 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 à valeur unique à l'aide de l'annotation @odata.bind.

Le corps de demande suivant publié dans l'ensemble d'entités de comptes créera un nouveau compte associé à un contact existant avec la valeur contactid de 00000000-0000-0000-0000-000000000001.

Demande

POST cc_WebAPI_ServiceURI/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@odata.bind":"/contacts(00000000-0000-0000-0000-000000000001)"
}

Réponse

HTTP/1.1 204 No Content
OData-Version: 4.0
OData-EntityId: cc_WebAPI_ServiceURI/accounts(00000000-0000-0000-0000-000000000002)

Notes

L'association d'entités de cette façon à une propriété de navigation avec une valeur de collection n'est pas prise en charge par l'API Web.

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

Notes

Cette fonctionnalité a été ajoutée avec la Mise à jour de décembre 2016 pour Dynamics 365 (en ligne et local).

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. L'option de requête $expand est ignorée si elle est utilisée.

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.

Requête

POST cc_WebAPI_ServiceURI/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
}

Réponse

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

{
    "@odata.context": "cc_WebAPI_ServiceURI/$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"
}

Voir aussi

Microsoft Dynamics 365

Partager via

Créer une entité à l'aide de l'API Web

Contenu de la rubrique

Création de base

Créer des entités associées en une opération

Associer des entités lors de la création

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

Voir aussi

Ressources supplémentaires