Mettre à jour et supprimer des lignes de table à l'aide de l'API web

Notes

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

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

Mise à jour de base

Les opérations de mise à jour utilisent le verbe PATCH HTTP. 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.

L'en-tête If-Match: * permet de garantir que vous ne créez pas de nouvel enregistrement en effectuant accidentellement une opération upsert. Pour plus d’informations : Éviter la création dans upsert.

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 cet objet JSON dans votre requête, chaque propriété est mise à jour même si la valeur est identique. Cela peut entraîner des événements système qui peuvent déclencher une logique métier qui prévoit que les valeurs aient changé. Les propriétés peuvent sembler avoir été mises à jour dans les données d'audit alors qu'elles n'ont pas changé.

Notes

La définition des attributs comprend une propriété RequiredLevel. Lorsqu'elle est définie sur SystemRequired, vous ne pouvez pas définir ces attributs sur une valeur nulle. Pour plus d'informations : Niveau requis des attributs

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

Demande

PATCH [Organization URI]/api/data/v9.0/accounts(00000000-0000-0000-0000-000000000001) HTTP/1.1  
Content-Type: application/json  
OData-MaxVersion: 4.0  
OData-Version: 4.0
If-Match: *  
  
{  
    "name": "Updated Sample Account ",  
    "creditonhold": true,  
    "address1_latitude": 47.639583,  
    "description": "This is the updated description of the sample account",  
    "revenue": 6000000,  
    "accountcategorycode": 2  
}  

Response

HTTP/1.1 204 No Content  
OData-Version: 4.0  
  

Notes

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

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

Pour extraire des données d'une entité que vous mettez à jour, vous pouvez composer votre requête 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.

Demande

PATCH [Organization URI]/api/data/v9.0/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
If-Match: * 
  
{"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": "[Organization URI]/api/data/v9.0/$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é Nom d'une entité de compte existante avec la valeur accountid de 00000000-0000-0000-0000-000000000001.

Demande

PUT [Organization URI]/api/data/v9.0/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 [Organization URI]/api/data/v9.0/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 approche alternative, voir Supprimer une référence à une table.

Opération Upsert sur une table

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

Rechercher des enregistrements dupliqués

Voir Détecter les doublons pendant l'opération de mise à jour à l'aide de l'API Web pour plus d'informations sur la recherche d'enregistrements en double pendant une opération de mise à jour.

Mettre à jour et supprimer des documents dans des partitions de stockage

Si vous mettez à jour ou supprimez des données d'entité stockées dans des partitions, veillez à spécifier la clé de partition lors de l'accès à ces données.

Plus d'information : Accéder plus rapidement aux données de table à l'aide de partitions de stockage

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)
Effectuer des opérations à l’aide de l’API Web
Composer des demandes Http et gérer les erreurs
Interroger les données à l'aide de l'API Web
Créer une table à l’aide de l’API web
Récupérer une table à l’aide de l’API web
Associer et dissocier les 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é).