Insert Or Merge Entity

Artículo
06/27/2023

La Insert Or Merge Entity operación actualiza una entidad existente o inserta una nueva entidad si no existe en la tabla. Dado que esta operación puede insertar o actualizar una entidad, también se conoce como una operación upsert .

Request

Puede construir la Insert Or Merge Entity solicitud como se indica a continuación. Se recomienda HTTPS. Reemplace los valores siguientes por los que considere adecuados:

myaccount por el nombre de la cuenta de almacenamiento
mytable por el nombre de la tabla
myPartitionKey y myRowKey con el nombre de la clave de partición y la clave de fila para la entidad que se va a actualizar

Método	URI de solicitud	Versión de HTTP
`MERGE`	`https://myaccount.table.core.windows.net/mytable(PartitionKey='myPartitionKey', RowKey='myRowKey')`	HTTP/1.1

Servicio de almacenamiento emulado

Al realizar una solicitud en el servicio de almacenamiento emulado, especifique el nombre de host del emulador y el puerto de Azure Table Storage como 127.0.0.1:10002, seguido del nombre de la cuenta de almacenamiento emulada.

Método	URI de solicitud	Versión de HTTP
`MERGE`	`http://127.0.0.1:10002/devstoreaccount1/mytable(PartitionKey='myPartitionKey', RowKey='myRowKey')`	HTTP/1.1

Table Storage en el emulador de Storage difiere de Azure Table Storage de varias maneras. Para más información, consulte Diferencias entre el emulador de Storage y los servicios de Azure Storage.

Parámetros del identificador URI

Puede especificar el siguiente parámetro adicional en el URI de solicitud.

Parámetro	Descripción
`timeout`	Opcional. El parámetro `timeout` se expresa en segundos. Para más información, consulte Establecimiento de tiempos de espera para las operaciones de Table Storage.

Encabezados de solicitud

En la tabla siguiente se describen los encabezados de solicitud requeridos y opcionales.

Encabezado de solicitud	Descripción
`Authorization`	Necesario. Especifica el esquema de autorización, el nombre de la cuenta y la firma. Para obtener más información, vea Autorización de solicitudes a Azure Storage.
`Date` o `x-ms-date`	Necesario. Especifica la hora universal coordinada (UTC) de la solicitud. Para obtener más información, vea Autorización de solicitudes a Azure Storage.
`x-ms-version`	Necesario. Debe establecerse en 2011-08-18 o posterior. Especifica la versión de la operación que se utiliza para esta solicitud. Para obtener más información, vea Versiones de los servicios de Azure Storage.
`Content-Type`	Necesario. Especifica el tipo de contenido de la carga. Los valores posibles son `application/atom+xml` y `application/json`. Para obtener más información sobre los tipos de contenido válidos, consulte Formato de carga para las operaciones de Table Storage.
`Content-Length`	Necesario. Longitud del cuerpo de la solicitud.
`x-ms-client-request-id`	Opcional. Proporciona un valor opaco generado por el cliente con un límite de caracteres de 1 kibibyte (KiB) que se registra en los registros cuando se configura el registro. Se recomienda encarecidamente usar este encabezado para correlacionar las actividades del lado cliente con las solicitudes que recibe el servidor. Para más información, consulte Supervisión de Azure Table Storage.

Cuerpo de la solicitud

La Insert Or Merge Entity operación envía la entidad que se va a insertar como un OData conjunto de entidades. Este conjunto de entidades puede ser una carga de Atom o JSON. Para obtener más información, consulte Inserción y actualización de entidades.

Nota

JSON es el formato de carga recomendado y es el único formato admitido para la versión 2015-12-11 y posteriores.

Response

La respuesta incluye un código de estado HTTP y un conjunto de encabezados de respuesta.

status code

Una operación correcta devuelve el código de estado 204 (No Content). Para obtener información sobre los códigos de estado, consulte Códigos de error y estado y Códigos de error de Table Storage.

Encabezados de respuesta

La respuesta incluye los encabezados siguientes. La respuesta también puede incluir encabezados HTTP adicionales y estándar. Todos los encabezados estándar se ajustan a la especificación del protocolo HTTP/1.1.

Encabezado de respuesta	Descripción
`ETag`	para `ETag` la entidad.
`x-ms-request-id`	Identifica de forma única la solicitud que se realizó y se puede usar para solucionar problemas de la solicitud. Para más información, consulte Solución de problemas de operaciones de API.
`x-ms-version`	Indica la versión de Table Storage usada para ejecutar la solicitud. Este encabezado se devuelve para las solicitudes realizadas en la versión 2009-09-19 y versiones posteriores.
`Date`	Valor de fecha y hora UTC que indica la hora a la que se inició la respuesta. El servicio genera este valor.
`x-ms-client-request-id`	Se puede usar para solucionar problemas de solicitudes y respuestas correspondientes. El valor de este encabezado es igual al valor del `x-ms-client-request-id` encabezado, si está presente en la solicitud. El valor tiene como máximo 1024 caracteres ASCII visibles. Si el `x-ms-client-request-id` encabezado no está presente en la solicitud, no estará presente en la respuesta.

Response body

Ninguno.

Authorization

El propietario de la cuenta puede realizar esta operación. Además, cualquier persona con una firma de acceso compartido que tenga permiso para realizar esta operación puede hacerlo.

Solicitud y respuesta de ejemplo

En los ejemplos siguientes se muestran solicitudes de ejemplo que usan fuentes JSON y Atom.

Nota

JSON es el formato de carga recomendado y es el único formato admitido para la versión 2015-12-11 y posteriores.

JSON (versión 2013-08-15 y posteriores)

A continuación se muestra una solicitud de ejemplo y una respuesta que usa JSON.

MERGE https://myaccount.table.core.windows.net/mytable(PartitionKey='myPartitionKey',RowKey='myRowKey')

La solicitud se envía con los encabezados siguientes:

x-ms-version: 2013-08-15  
Content-Type: application/json  
x-ms-date: Tue, 30 Aug 2013 18:10:24 GMT  
Authorization: SharedKeyLite myaccount:u0sWZKmjBD1B7LY/CwXWCnHdqK4B1P4z8hKy9SVW49o=  
Content-Length: 1135  
DataServiceVersion: 3.0;NetFx  
MaxDataServiceVersion: 3.0;NetFx

La solicitud se envía con el cuerpo JSON siguiente:

{  
   "Address":"Santa Clara",  
   "Age":23,  
   "AmountDue":200.23,  
   "CustomerCode@odata.type":"Edm.Guid",  
   "CustomerCode":"c9da6455-213d-42c9-9a79-3e9149a57833",  
   "CustomerSince@odata.type":"Edm.DateTime",  
   "CustomerSince":"2008-07-10T00:00:00",  
   "IsActive":false,  
   "NumberOfOrders@odata.type":"Edm.Int64",  
   "NumberOfOrders":"255",  
   "PartitionKey":"mypartitionkey",  
   "RowKey":"myrowkey"  
}

Una vez enviada la solicitud, se devuelve la respuesta siguiente:

  
HTTP/1.1 204 No Content  
  
Connection: Keep-Alive  
x-ms-request-id: 2c085f8f-11a4-4e1d-bd49-82c6bd87649d  
Content-Length: 0  
Cache-Control: no-cache  
Date: Tue, 30 Aug 2013 18:12:54 GMT  
ETag: W/"0x5B168C7B6E589D2"  
DataServiceVersion: 3.0;NetFx  
MaxDataServiceVersion: 3.0;NetFx  
Server: Windows-Azure-Table/1.0 Microsoft-HTTPAPI/2.0

Fuente Atom (versiones anteriores a 2015-12-11)

A continuación se muestra una solicitud de ejemplo y una respuesta que usa Atom:

MERGE https://myaccount.table.core.windows.net/mytable(PartitionKey='myPartitionKey',RowKey='myRowKey')

La solicitud se envía con los encabezados siguientes:

x-ms-version: 2013-08-15  
Accept: application/atom+xml,application/xml  
Accept-Charset: UTF-8  
Content-Type: application/atom+xml  
x-ms-date: Tue, 12 Nov 2013 18:10:24 GMT  
Authorization: SharedKeyLite myaccount:u0sWZKmjBD1B7LY/CwXWCnHdqK4B1P4z8hKy9SVW49o=  
Content-Length: 1135  
DataServiceVersion: 1.0;NetFx  
MaxDataServiceVersion: 2.0;NetFx

La solicitud se envía con el cuerpo XML siguiente:

<?xml version="1.0" encoding="utf-8"?>  
<entry xmlns:d="http://schemas.microsoft.com/ado/2007/08/dataservices" xmlns:m="http://schemas.microsoft.com/ado/2007/08/dataservices/metadata" xmlns="https://www.w3.org/2005/Atom">  
  <title />  
  <updated>2013-11-12T18:09:37.168836Z</updated>  
  <author>  
    <name />  
  </author>  
<id>https://myaccount.table.core.windows.net/mytable(PartitionKey='mypartitionkey',RowKey='myrowkey')</id>  
  <content type="application/xml">  
    <m:properties>  
      <d:Address>Santa Clara</d:Address>  
      <d:Age m:type="Edm.Int32">23</d:Age>  
      <d:AmountDue m:type="Edm.Double">200.23</d:AmountDue>  
      <d:CustomerCode m:type="Edm.Guid">c9da6455-213d-42c9-9a79-3e9149a57833</d:CustomerCode>  
      <d:CustomerSince m:type="Edm.DateTime">2008-07-10T00:00:00Z</d:CustomerSince>  
      <d:IsActive m:type="Edm.Boolean">false</d:IsActive>  
      <d:NumOfOrders m:type="Edm.Int64">255</d:NumOfOrders>  
      <d:PartitionKey>mypartitionkey</d:PartitionKey>  
      <d:RowKey>myrowkey1</d:RowKey>  
    </m:properties>  
  </content>  
</entry>

Una vez enviada la solicitud, se devuelve la respuesta siguiente:

HTTP/1.1 204 No Content  
  
Connection: Keep-Alive  
x-ms-request-id: 2c085f8f-11a4-4e1d-bd49-82c6bd87649d  
Content-Length: 0  
Cache-Control: no-cache  
Date: Tue, 12 Nov 2013 18:12:54 GMT  
ETag: W/"0x5B168C7B6E589D2"  
DataServiceVersion: 1.0;NetFx  
MaxDataServiceVersion: 2.0;NetFx  
Server: Windows-Azure-Table/1.0 Microsoft-HTTPAPI/2.0

Comentarios

La Insert Or Merge Entity operación usa el MERGE verbo . Debe llamar a la operación mediante la versión 2011-08-18 o posterior. Además, esta operación no usa el If-Match encabezado . Estos atributos distinguen esta operación de la operación Update Entity, aunque el cuerpo de la solicitud es el mismo para ambas operaciones.

Si usa la Insert Or Merge Entity operación para combinar una entidad, se conservan las propiedades de la entidad anterior, si la solicitud no las define ni las incluye. Las propiedades con un null valor también se conservan.

Al llamar a la Insert or Merge Entity operación, debe especificar valores para las propiedades del PartitionKey sistema y RowKey . Juntas, estas propiedades forman la clave principal y deben ser únicas dentro de la tabla.

PartitionKey Los valores y RowKey deben ser valores de cadena. Cada valor de clave puede tener un tamaño de hasta 64 KiB. Si usa un valor entero para el valor de clave, debe convertir el entero en una cadena de ancho fijo. Esto se debe a que se ordenan canónicamente. Por ejemplo, convierta el valor 1 en 0000001 para garantizar una ordenación adecuada.

Para escribir explícitamente una propiedad, especifique el tipo adecuado OData estableciendo el m:type atributo dentro de la definición de propiedad en la fuente Atom. Para obtener más información sobre cómo escribir propiedades, vea Insertar y actualizar entidades.

Cualquier aplicación que pueda autorizar y enviar una HTTP MERGE solicitud puede insertar o actualizar una entidad.

Para obtener información sobre cómo realizar operaciones upsert por lotes, consulte Realización de transacciones de grupo de entidades.

Consulte también

Autorización de solicitudes a Azure Storage
Establecimiento de los encabezados de versión del servicio de datos de OData
Inserción y actualización de entidades
Estado y códigos de error
Códigos de error de Table Storage