Mettre à jour et supprimer des entités à 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

Les opérations pour modifier les données sont une partie fondamentale de l'API Web. En plus d'une mise à jour et d'une suppression simples, vous pouvez exécuter des opérations sur les attributs uniques et composer des requêtes upsert qui mettront à jour ou insèreront une entité selon qu'elle existe ou non.

Notes

Les métadonnées qui définissent les entités sont mises à jour de manière différente.Pour plus d'informations :Créer et mettre à jour les définitions d'entité à l’aide de l'API Web

Contenu de la rubrique

Mise à jour de base

Mettre à jour une entité avec les données retournées

Mettre à jour une valeur de propriété unique

Supprimer une valeur de propriété unique

Utilisation de Upsert avec une entité

Suppression de base

Mise à jour de base

Les opérations de mise à jour utilisent le verbe HTTP PATCH. Passez un objet JSON contenant les propriétés à mettre à jour à l'URI qui représente l'entité. Une réponse avec un statut de 204 est renvoyée si la mise à jour est réussie.

Cet exemple met à jour un enregistrement de compte existant avec la valeur accountid de 00000000-0000-0000-0000-000000000001.

Important

En mettant une entité à jour, ajoutez uniquement les propriétés que vous modifiez dans le corps de requête. En mettant simplement à jour les propriétés d'une entité que vous avez précédemment récupérée, et en incluant JSON dans votre requête, chaque propriété est mise à jour même si la valeur est identique. Les propriétés peuvent sembler avoir été mises à jour dans les données d'audit alors qu'elles n'ont pas changé.

Demande

PATCH cc_WebAPI_ServiceURI/accounts(00000000-0000-0000-0000-000000000001) HTTP/1.1
Content-Type: application/json
OData-MaxVersion: 4.0
OData-Version: 4.0

{
    "name": "Updated Sample Account ",
    "creditonhold": true,
    "address1_latitude": 47.639583,
    "description": "This is the updated description of the sample account",
    "revenue": 6000000,
    "accountcategorycode": 2
}

Réponse

HTTP/1.1 204 No Content
OData-Version: 4.0

Notes

Voir Associer des entités lors de la mise à jour pour des informations sur l'association d'entités lors de la mise à jour.

Mettre à jour 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).

Pour extraire des données d'une entité que vous mettez à jour, vous pouvez composer votre demande PATCH de manière à ce que les données de l'enregistrement créé soient retournées avec le statut 200 (OK). 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.

Cet exemple met à jour une entité Compte et retourne les données demandées dans la réponse.

Requête

PATCH cc_WebAPI_ServiceURI/accounts(00000000-0000-0000-0000-000000000001)?$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":"Updated Sample Account"}

Réponse

HTTP/1.1 200 OK
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/\"536537\"",
    "accountid": "00000000-0000-0000-0000-000000000001",
    "accountcategorycode": 1,
    "description": "This is the description of the sample account",
    "address1_latitude": 47.63958,
    "creditonhold": false,
    "name": "Updated Sample Account",
    "createdon": "2016-09-28T23:14:00Z",
    "revenue": 5000000.0000,
    "_transactioncurrencyid_value": "048dddaa-6f7f-e611-80d3-00155db5e0b6"
}

Mettre à jour une valeur de propriété unique

Lorsque vous souhaitez mettre à jour une seule valeur de propriété unique, utilisez une requête PUT avec le nom de propriété ajouté à l'Uri de l'entité.

L'exemple suivant met à jour la propriété name d'une entité de compte existante avec la valeur accountid de 00000000-0000-0000-0000-000000000001.

Demande

PUT cc_WebAPI_ServiceURI/accounts(00000000-0000-0000-0000-000000000001)/name HTTP/1.1
Content-Type: application/json
OData-MaxVersion: 4.0
OData-Version: 4.0

{"value": "Updated Sample Account Name"}

Réponse

HTTP/1.1 204 No Content
OData-Version: 4.0

Supprimer une valeur de propriété unique

Pour supprimer la valeur d'une propriété unique, utilisez une requête DELETE avec le nom de propriété ajouté à l'Uri de l'entité.

L'exemple suivant supprime la valeur de la propriété description d'une entité de compte existante avec la valeur accountid de 00000000-0000-0000-0000-000000000001.

Demande

DELETE cc_WebAPI_ServiceURI/accounts(00000000-0000-0000-0000-000000000001)/description HTTP/1.1
Content-Type: application/json
OData-MaxVersion: 4.0
OData-Version: 4.0

Réponse

HTTP/1.1 204 No Content
OData-Version: 4.0

Notes

Cela ne peut pas être utilisé avec une propriété de navigation à valeur unique pour dissocier deux entités. Pour une solution alternative, voir Supprimer une référence à une entité.

Utilisation de Upsert avec une entité

Une opération upsert est exactement comme une mise à jour. Elle utilise une requête PATCH et utilise une URI pour faire référence à une entité spécifique. La différence est que si l'entité n'existe pas elle est créée. Si elle existe déjà, elle sera mise à jour. Normalement lorsque vous créez une entité vous laissez le système attribuer un identificateur unique. C'est une pratique recommandée. Mais si vous devez créer un enregistrement avec une valeur spécifique id, une opération upsert vous permet de le faire. Cela peut être utile dans le cas où vous synchronisez les données dans différents systèmes.

Il arrive toutefois que dans certaines situations vous souhaitez utiliser upsert, mais vous voulez éviter une des actions par défaut potentielles : créer ou mettre à jour. Vous pouvez y parvenir en ajoutant des en-têtes If-Match ou If-None-Match. Pour plus d'informations, voir Limiter les opérations upsert.

Suppression de base

Une opération de suppression est très simple. Utilisez le verbe DELETE avec l'URI de l'entité que vous souhaitez supprimer. Ce message d'exemple entraîne la suppression d'une entité de compte avec la valeur de clé primaire accountid égale à 00000000-0000-0000-0000-000000000001.

Demande

DELETE cc_WebAPI_ServiceURI/accounts(00000000-0000-0000-0000-000000000001) HTTP/1.1
Content-Type: application/json
OData-MaxVersion: 4.0
OData-Version: 4.0

Réponse
Si l'entité existe, vous recevrez une réponse normale avec le statut 204 pour indiquer que la suppression a réussi. Si l'entité n'est pas détectée, vous recevrez une réponse avec le statut 404.
```
HTTP/1.1 204 No Content
OData-Version: 4.0
```

Voir aussi

Microsoft Dynamics 365

Mettre à jour et supprimer des entités à l'aide de l'API Web

Contenu de la rubrique

Mise à jour de base

Mettre à jour une entité avec les données retournées

Mettre à jour une valeur de propriété unique

Supprimer une valeur de propriété unique

Utilisation de Upsert avec une entité

Suppression de base

Voir aussi

Ressources supplémentaires