Partager via

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

Les opérations de modification des données font partie intégrante de l’API web. En plus des opérations de mise à jour et de suppression simples, 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èreront des données selon qu’elles existent.

Mise à jour de base

Les opérations de mise à jour utilisent le verbe HTTP PATCH . Transmettez un objet JSON contenant les propriétés que vous souhaitez mettre à jour vers l’URI qui représente l’enregistrement. Une réponse avec un état 204 No Content est retournée si la mise à jour réussit.

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

Lors de la mise à jour d’une entité, incluez uniquement les propriétés que vous modifiez dans le corps de la demande. Il suffit de mettre à jour les propriétés d’une entité que vous avez récupérées précédemment, et d’inclure ce JSON dans votre requête, met à jour chaque propriété même si la valeur est la même. Cela peut entraîner des événements système qui peuvent déclencher une logique métier qui s’attend à ce que les valeurs aient changé. Cela peut donner l'impression que les propriétés ont été mises à jour dans les données d'audit alors qu'en réalité, elles n'ont pas changé.

Lorsque vous mettez à jour la statecode propriété, il est important de toujours définir le paramètre souhaité statuscode. 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.

Note

La définition des attributs inclut une RequiredLevel propriété. Lorsque cette valeur est définie SystemRequired, vous ne pouvez pas définir ces attributs sur une valeur Null. Plus d’informations : niveau d’exigence d’attribut

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

Requête :

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

Note

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

Mettre à jour avec les données retournées

Pour récupérer des données à partir d’une entité que vous mettez à jour, vous pouvez composer votre PATCH demande afin que les données de l’enregistrement créé soient retournées avec l’état 200 (OK). Pour obtenir ce résultat, vous devez utiliser l’en-tête Prefer: return=representation de requête.

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

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

Requête :

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

Plus d’informations :

Mettre à jour une valeur de propriété unique

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

L’exemple suivant met à jour la name propriété d’une ligne existante account avec la accountid valeur 00000000-0000-0000-0000-0000000001.

Requête :

PUT [Organization URI]/api/data/v9.2/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 DELETE requête avec le nom de propriété ajouté à l’URI de l’entité.

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

Requête :

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

Note

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.

Insérer ou mettre à jour une ligne de table

Une opération upsert est similaire à une mise à jour. Il utilise une requête PATCH et un URI pour référencer 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 peut ne pas contenir de référence à la clé primaire de la table Dataverse. Vous pouvez donc configurer d’autres clés pour la table Dataverse à l’aide de 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 autres clés définies pour une table dans les annotations du type d’entité dans le document de service $metadata. Plus d’informations : Autres clés.

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

Requête :

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. Notez que l’en-tête OData-EntityId de réponse 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 identique, vous ne pouvez pas savoir si l’opération a représenté une Create ou une Update opération.

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

Lorsque vous utilisez d’autres clés, vous ne devez pas inclure les valeurs de clé de remplacement dans le corps de la requête.

  • Lorsqu’un upsert représente un Update, ces autres valeurs de clé sont ignorées. Vous ne pouvez pas mettre à jour d’autres valeurs de clé lors de leur utilisation 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 demande.

Plus d’informations : Utiliser Upsert pour créer ou mettre à jour un enregistrement

Note

Normalement, lors de la création d’un enregistrement, vous laisserez le système attribuer une valeur GUID pour 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 et améliore les performances. Toutefois, si vous devez créer un enregistrement avec une valeur de clé primaire spécifique, par exemple lorsque la valeur GUID de clé est générée par un système externe, l’opération upsert permet de procéder ainsi.

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

Parfois, il existe des situations où vous souhaitez effectuer un upsert, mais vous souhaitez empêcher l’une des opérations potentielles : créer ou mettre à jour. Vous pouvez le faire à l’aide 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 simple. Utilisez le DELETE verbe avec l’URI de l’entité que vous souhaitez supprimer. Cet exemple de message supprime une entité de compte avec la valeur de clé accountid primaire égale à 0000000-0000-0000-0000-0000-000000001.

Requête :

DELETE [Organization URI]/api/data/v9.2/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 obtenez une réponse normale avec l’état 204 pour indiquer que la suppression a réussi. Si l’entité est introuvable, vous obtenez une réponse avec l’état 404.

HTTP/1.1 204 No Content  
OData-Version: 4.0

Rechercher des enregistrements dupliqués

Pour plus d’informations sur la façon de rechercher des enregistrements en double pendant une opération de mise à jour, consultez 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 cette écriture, l’action DeleteMultiple est une fonctionnalité d’aperçu. Les tables standard ne prennent pas en charge cette action, mais toutes les tables élastiques le font.

Note

Pour les tables standard, nous vous recommandons d’utiliser l’action BulkDelete, qui permet la suppression asynchrone d’enregistrements qui correspondent à une requête. Plus d’informations : Supprimer des données en bloc

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 : Choix d’une valeur PartitionId

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 ligne de table à l’aide de l’API web
Récupérer une ligne 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 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