Compartir por

Actualizar e eliminar as filas das mesas usando a API web

As operacións que modifican datos son unha parte central da API web. Ademais das operacións sinxelas de actualización e eliminación, podes realizar operacións sobre columnas de táboa única (atributos de entidade) e compoñer solicitudes upsert que actualizan ou insiren datos dependendo de se existen.

Actualización básica

As operacións de actualización usan o verbo HTTP PATCH . Pasa un obxecto JSON que conteña as propiedades que desexa actualizar ao URI que representa o rexistro. Se a actualización é exitosa, a resposta devolve un estado de 204 No Content.

A If-Match: * cabeceira asegura que non se crea un novo rexistro realizando accidentalmente unha operación de upsert. Para máis información, consulta Prevenir crear en upsert.

Importante

Ao actualizar unha entidade, inclúa só as propiedades que está a cambiar no corpo da solicitude. Se actualizas unha entidade incluíndo todas as propiedades dunha entidade que recuperaches previamente, a operación actualiza cada propiedade aínda que o valor sexa o mesmo. Esta actualización pode causar eventos do sistema que activan a lóxica de negocio que espera que os valores cambiaron. Pode facer que as propiedades parezan actualizadas nos datos de auditoría cando en realidade non cambiaron.

Cando actualices a statecode propiedade, sempre configura o valor desexado statuscode. Os statecode valores e statuscode dependen uns dos outros. Para un valor dado statecode , poden existir múltiples valores válidos statuscode . Con todo, cada statecode columna ten un único valor DefaultStatus configurado. Cando actualizas statecode sen especificar un statuscode, o sistema establece o valor de estado por defecto. Ademais, se activas a auditoría na táboa e na statuscode columna, o valor cambiado da statuscode columna non se captura nos datos da auditoría a menos que o especifiques na operación de actualización.

Nota

A definición de atributos inclúe unha RequiredLevel propiedade. Cando esta propiedade se establece en SystemRequired, non podes establecer estes atributos a un valor nulo. Para máis información, véxase Nivel de requisito de atributo.

Este exemplo actualiza un rexistro de conta existente co accountid valor de 00000000-0000-0000-0000-0000000000001.

Solicitude:

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  
}

Resposta:

HTTP/1.1 204 No Content  
OData-Version: 4.0

Nota

Para información sobre asociar e disociar entidades na actualización, véxase Usar propiedades de navegación de valor único.

Actualización cos datos devoltos

Para recuperar datos dunha entidade que estás actualizando, compón a túa PATCH solicitude para que devolva datos do rexistro actualizado cun estado de 200 (OK). Para obter este resultado, usa a Prefer: return=representation cabeceira de solicitude.

Para controlar que propiedades se devolven, engade a $select opción de consulta á URL do conxunto de entidades. A $expand opción de consulta ignorarase se se usa.

Este exemplo actualiza unha entidade de conta e devolve os datos solicitados na resposta.

Solicitude:

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"}

Resposta:

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"  
}

Actualizar varios rexistros nunha soa solicitude

O xeito máis rápido de actualizar varios rexistros do mesmo tipo nunha soa solicitude é usar a acción UpdateMultiple. Non todas as táboas estándar soportan esta acción, pero todas as táboas elásticas si.

Máis información:

Actualizar o valor dunha única propiedade

Para actualizar un único valor dunha propiedade, usa unha PUT solicitude e engade o nome da propiedade ao Uri da entidade.

O seguinte exemplo actualiza a name propiedade dunha fila existente account co accountid valor de 00000000-0000-0000-0000-000000000001.

Solicitude:

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"}

Resposta:

HTTP/1.1 204 No Content  
OData-Version: 4.0

Eliminar un único valor de propiedade

Para eliminar o valor dunha única propiedade, usa unha DELETE solicitude co nome da propiedade engadido ao URI da entidade.

O seguinte exemplo elimina o valor da description propiedade dunha entidade da conta co accountid valor de 00000000-0000-0000-0000-000000000001.

Solicitude:

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

Resposta:

HTTP/1.1 204 No Content  
OData-Version: 4.0

Nota

Non podes usar este enfoque cunha propiedade de navegación de valor único para disociar dúas entidades. Para un enfoque alternativo, véxase Desasociar usando unha propiedade de navegación de valor único.

Levantar unha fila de táboa

Unha operación de actualización é semellante a unha actualización. Usa unha PATCH solicitude e usa un URI para facer referencia a un rexistro específico. A diferenza é que se o rexistro non existe, créase. Se xa existe, está actualizado.

Upsert é valioso á hora de sincronizar datos entre sistemas externos. O sistema externo pode non conter unha referencia á clave primaria da táboa Dataverse, polo que podes configurar claves alternativas para a táboa Dataverse usando valores do sistema externo que identifican de forma única o rexistro en ambos sistemas. Máis información: Definir chaves alternativas para referenciar filas

Pode ver as claves alternativas definidas para unha táboa nas anotacións do tipo de entidade no documento de servizo $metadata. Máis información: Chaves alternativas.

No seguinte exemplo, hai unha táboa co nome sample_thing que ten unha clave alternativa que se refire a dúas columnas: sample_key1 e sample_key2, que están definidas para almacenar valores enteiros.

Solicitude:

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"
}

Para ambas operacións de creación ou actualización, obtés a mesma resposta. Observa como a cabeceira de OData-EntityId resposta usa os valores de clave en lugar do identificador de clave primaria GUID para o rexistro.

Resposta:

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)

Debido a que a resposta é a mesma, non podes saber se a operación representaba unha Create operación ou Update .

Se precisas saber, podes usar a cabeceira da Prefer: return=representation solicitude. Ao usar esta cabeceira, recibes unha 201 Created resposta cando se crea un rexistro e unha 200 OK resposta cando o rexistro se actualiza. Esta opción engade unha Retrieve operación, que ten un impacto no rendemento. Se usa a cabeceira da Prefer: return=representation solicitude, asegúrese de que $select inclúe a cantidade mínima de datos, preferentemente só a columna de clave primaria. Máis información: Actualizar cos datos devoltos e Crear cos datos devoltos.

Ao usar claves alternativas, non inclúas os valores alternativos das claves no corpo da solicitude.

  • Cando un upsert representa un Update, estes valores de clave alternativos son ignorados. Non podes actualizar os valores de clave alternativos mentres os usas para identificar o rexistro.
  • Cando un upsert representa un Create, os valores clave do URL establécense para o rexistro se non están presentes no corpo. Polo tanto, non é necesario incluílos no corpo da solicitude.

Máis información: Usar Upsert para crear ou actualizar un rexistro

Nota

Normalmente, ao crear un novo rexistro, deixas que o sistema asigne un valor GUID para a clave primaria. Esta práctica é mellor porque o sistema xera claves optimizadas para o índice e esta elección mellora o rendemento. Pero se precisa crear un rexistro cun valor de clave primaria específico, como cando o valor GUID da clave é xerado por un sistema externo, a upsert operación proporciona un xeito de facelo.

Evitar a creación ou actualización con upsert

Ás veces, queres realizar un upsert pero evitar unha das operacións potenciais: crear ou actualizar. Podes evitar estas operacións usando os If-Match encabezados de ou.If-None-Match Para obter máis información, consulte Limitar as operacións de upsert.

Eliminación básica

A operación de borrado é sinxela. Use o verbo DELETE co URI da entidade que desexa eliminar. Esta mensaxe de exemplo elimina unha entidade de conta cuxo valor clave accountid primario é igual a 00000000-0000-0000-0000-000000000001.

Solicitude:

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

Resposta:

Se a entidade existe, obtén unha resposta normal co estado 204 para indicar que a eliminación foi exitosa. Se non se atopa a entidade, obterás unha resposta co estado 404.

HTTP/1.1 204 No Content  
OData-Version: 4.0

Comprobar se hai rexistros duplicados

Para obter máis información sobre como comprobar rexistros duplicados durante unha operación de actualización, consulte Detectar duplicados durante a operación de actualización usando a API web.

Eliminar varios rexistros nunha soa solicitude

Para eliminar múltiples rexistros do mesmo tipo nunha soa solicitude, usa a DeleteMultiple acción. As mesas estándar non soportan esta DeleteMultiple acción, pero todas as táboas elásticas si.

Nota

Para táboas estándar, usa a acción BulkDelete. Esta acción permite a eliminación asincrónica de rexistros que coinciden cunha consulta. Para máis información, véxase Eliminar datos en bloque.

Máis información:

Actualizar e eliminar documentos en particións de almacenamento

Se estás actualizando ou eliminando datos de táboas elásticas almacenados nas particións, especifica a clave de partición cando accedas a eses datos.

Máis información: Escoller un valor PartitionId

Véxase tamén

Exemplo de operacións básicas da API web (C#)
Exemplo de operacións básicas da API web (JavaScript do lado do cliente)
Realizar operacións usando a API Web
Composición de solicitudes HTTP e xestionar erros
Consulta datos usando a API Web
Crear unha fila de táboa usando a API web
Recuperar unha fila de táboa usando a API web
Asociar e desasociar filas de táboa usando a API web
Usar funcións da API web
Use accións da API web
Executar operacións por lotes usando a API web
Suplantar a outro usuario usando a API web
Realizar operacións condicionais usando a API web

  • Last updated on