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

Article
08/26/2023

Les opérations pour modifier les données sont une partie fondamentale de l’API Web. En plus de simples opérations de mise à jour et de suppression, vous pouvez effectuer des opérations sur des colonnes de table uniques (attributs d’entité) et composer des requêtes upsert qui mettent à jour ou insèrent 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’enregistrement. Une réponse avec un statut 204 No Content est renvoyée si la mise à jour a réussi.

L’en-tête If-Match: * garantit que vous ne créez pas d’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é.

Lorsque vous mettez à jour la propriété statecode, il est important de toujours définir le statuscode souhaité. statecode et statuscode ont des valeurs dépendantes. Il peut y avoir plusieurs valeurs statuscode valides pour une valeur statecode donnée, mais chaque colonne statecode a une seule valeur de DefaultStatus configurée. Lorsque vous mettez à jour statecode sans spécifier de statuscode, la valeur d’état par défaut est définie par le système. De plus, lorsque l’audit est activé sur la table et la colonne statuscode, la valeur modifiée de la colonne statuscode ne sera pas capturée dans les données d’audit, sauf si elle est spécifiée dans l’opération de mise à jour.

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  
}

Réponse :

HTTP/1.1 204 No Content  
OData-Version: 4.0

Notes

Pour plus d’informations sur l’association et la dissociation d’entités lors de la mise à jour, voir Utilisation des propriétés de navigation à valeur unique.

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 l’en-tête de demande Prefer: return=representation.

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 plusieurs enregistrements dans une seule requête

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

Pour plus d’informations :

Mettre à jour une valeur de propriété unique

Lorsque vous souhaitez mettre à jour une seule valeur de propriété, 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 ligne account 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 autre approche, voir Dissociation d’une propriété de navigation à valeur unique.

Opération Upsert sur une ligne

Une opération upsert est similaire à une mise à jour. Elle utilise une requête PATCH et utilise une URI pour faire référence à un enregistrement spécifique. La différence est que si l’enregistrement n’existe pas, il est créé. S’il existe déjà, il est mis à jour.

Upsert est utile lors de la synchronisation des données entre des systèmes externes. Le système externe ne doit pas contenir de référence à la clé primaire de la table Dataverse, afin que vous puissiez configurer des clés secondaires pour la table Dataverse en utilisant les valeurs du système externe qui identifient de manière unique l’enregistrement sur les deux systèmes. Pour plus d’informations : Définir des clés secondaires pour référencer les lignes

Vous pouvez voir toutes les clés secondaires définies pour une table dans les annotations pour le type d’entité du document de service $metadata. Pour plus d’informations, voir : Clés secondaires.

Dans l’exemple suivant, une table portant le nom sample_thing a un clé secondaire qui fait référence à deux colonnes : sample_key1 et sample_key2, qui sont toutes deux définies pour stocker des valeurs entières.

Demande :

PATCH [Organization URI]/api/data/v9.2/sample_things(sample_key1=1,sample_key2=1) HTTP/1.1
Accept: application/json 
OData-MaxVersion: 4.0
OData-Version: 4.0
If-None-Match: null
Content-Type: application/json

{
    "sample_name": "1:1"
}

Pour les opérations de création ou de mise à jour, vous obtenez la même réponse. Remarquez comment l’en-tête de réponse OData-EntityId utilise les valeurs de clé plutôt que l’identificateur de clé primaire GUID pour l’enregistrement.

Réponse :

HTTP/1.1 204 No Content
OData-Version: 4.0
OData-EntityId: [Organization URI]/api/data/v9.2/sample_things(sample_key1=1,sample_key2=1)

Étant donné que la réponse est la même, vous ne pouvez pas savoir si l’opération représentait une opération Create ou Update.

Si besoin, vous pouvez utiliser l’en-tête de demande Prefer: return=representation. Avec cet en-tête, vous obtenez une réponse 201 Created lorsqu’un enregistrement est créé et une réponse 200 OK lorsque l’enregistrement est mis à jour. Cette option ajoute une opération Retrieve, qui a un impact sur les performances. Si vous utilisez l’en-tête de demande Prefer: return=representation, assurez-vous que votre $select inclut la quantité minimale de données, de préférence uniquement la colonne de clé primaire. Plus d’information : Mise à jour avec les données renvoyées et Créer avec les données renvoyées.

Lorsque vous utilisez des clés secondaires, vous ne devez pas inclure les valeurs de clé secondaire dans le corps de la requête.

Lorsqu’un upsert représente un Update, ces valeurs de clé secondaire sont ignorées. Vous ne pouvez pas mettre à jour les valeurs de clé secondaire tout en les utilisant pour identifier l’enregistrement.
Lorsqu’un upsert représente a Create, les valeurs de clé dans l’URL sont définies pour l’enregistrement si elles ne sont pas présentes dans le corps. Il n’est donc pas nécessaire de les inclure dans le corps de la requête.

Pour plus d’informations : Utilisation de Créer ou Mettre à jour un enregistrement

Notes

Normalement quand vous créez un enregistrement, vous laissez le système attribuer une valeur de GUID poru la clé primaire. Il s’agit d’une bonne pratique car le système génère des clés optimisées pour l’index, ce qui améliore les performances. Mais si vous devez créer un enregistrement avec une valeur de clé primaire spécifique, par exemple quand la valeur GUID de la clé est générée par un système externe, l’opération upsert fournit un moyen de le faire.

Empêcher la création ou la mise à jour avec upsert

Il arrive toutefois que dans certaines situations vous souhaitez utiliser upsert, mais vous voulez éviter une des opérations potentielles : créer ou mettre à jour. Vous pouvez le faire avec les 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 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é est introuvable, vous recevez une réponse avec le statut 404.

HTTP/1.1 204 No Content  
OData-Version: 4.0

Rechercher des enregistrements dupliqués

Pour plus d’informations sur la recherche d’enregistrements en double pendant une opération de mise à jour, voir Détecter les doublons pendant l’opération de mise à jour à l’aide de l’API Web.

Supprimer plusieurs enregistrements dans une seule requête

La façon la plus rapide de supprimer plusieurs enregistrements du même type dans une seule requête consiste à utiliser l’action DeleteMultiple. Au moment de la rédaction de cet article, l’action DeleteMultiple est une fonctionnalité en version préliminaire. Les tables standard ne prennent pas en charge cette action, contrairement aux tables élastiques.

Notes

Pour les tables standard, nous vous recommandons d’utiliser la classe BulkDelete, qui active la suppression asynchrone des enregistrements correspondant à une requête. Pour plus d’informations : Supprimer des données en bloc

Pour plus d’informations :

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

Si vous mettez à jour ou supprimez des données de table élastique stockées dans des partitions, assurez-vous de spécifier la clé de partition lors de l’accès à ces données.

Plus d’informations : Choisir une valeur PartitionId

Voir aussi

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

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

Mise à jour de base

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

Mettre à jour plusieurs enregistrements dans une seule requête

Mettre à jour une valeur de propriété unique

Supprimer une valeur de propriété unique

Opération Upsert sur une ligne

Empêcher la création ou la mise à jour avec upsert

Suppression de base

Rechercher des enregistrements dupliqués

Supprimer plusieurs enregistrements dans une seule requête

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

Voir aussi

Commentaires

Ressources supplémentaires