Crear una fila de tabla usando la API web

Artigo
07/06/2022
3 minutos de lectura

Nota

¿No está seguro de entidad frente a tabla? Vea Desarrolladores: comprender la terminología en Microsoft Dataverse.

Use una solicitud POST para enviar datos para crear una fila de tabla (registro de entidad). Puede crear varias filas de tabla relacionadas en una sola operación usando inserción profunda. También necesita saber cómo establecer valores para asociar una nueva fila de tabla a tablas existentes usando la anotación @odata.bind.

Nota

Para obtener información sobre cómo crear y actualizar las definiciones de tabla (entidad) mediante la API web, consulte Crear y actualizar definiciones de tablas mediante la API web.

Crear básico

En este ejemplo crea un nuevo registro de entidad de cuenta. El encabezado OData-EntityId de respuesta contiene el Uri de la entidad creada.

Solicitud


POST [Organization URI]/api/data/v9.0/accounts HTTP/1.1
Content-Type: application/json; charset=utf-8
OData-MaxVersion: 4.0
OData-Version: 4.0
Accept: application/json

{
    "name": "Sample Account",
    "creditonhold": false,
    "address1_latitude": 47.639583,
    "description": "This is the description of the sample account",
    "revenue": 5000000,
    "accountcategorycode": 1
}

Respuesta


HTTP/1.1 204 No Content
OData-Version: 4.0
OData-EntityId: [Organization URI]/api/data/v9.0/accounts(7eb682f1-ca75-e511-80d4-00155d2a68d1)

Para crear un nuevo registro de entidad debe identificar los nombres y los tipos de propiedad válidos. Para todas las entidades y atributos del sistema (columnas de la tabla), puede encontrar esta información en tema para esa entidad en Acerca de la referencia de la tabla. Para entidades o atributos personalizados, consulte la definición de esa entidad en Documento de $metadatos CSDL. Más información: EntityTypes de la API web

Crear con datos devueltos

Puede crear su solicitud POST de forma que los datos del registro creado sean devueltos con un estado de 201 (Created). Para obtener este resultado, debe usar la preferencia return=representation en los encabezados de solicitud.

Para controlar qué propiedades se devuelven, anexe la opción de consulta $select a la dirección URL del conjunto de entidades. También puede utilizar $expand para devolver entidades relacionadas.

Cuando se crea una entidad de esta forma, el encabezado OData-EntityId que contiene el URI al registro creado no se vuelve.

Este ejemplo crea una nueva entidad de cuenta y devuelve los datos solicitados en la respuesta.

Solicitud


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

{
   "name": "Sample Account",
   "creditonhold": false,
   "address1_latitude": 47.639583,
   "description": "This is the description of the sample account",
   "revenue": 5000000,
   "accountcategorycode": 1
}

Response


HTTP/1.1 201 Created
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/\"536530\"",
    "accountid": "d6f193fc-ce85-e611-80d8-00155d2a68de",
    "accountcategorycode": 1,
    "description": "This is the description of the sample account",
    "address1_latitude": 47.63958,
    "creditonhold": false,
    "name": "Sample Account",
    "createdon": "2016-09-28T22:57:53Z",
    "revenue": 5000000.0000,
    "_transactioncurrencyid_value": "048dddaa-6f7f-e611-80d3-00155db5e0b6"
}

Puede crear entidades relacionadas entre sí definiéndolas como valores de propiedades de navegación. Esto se conoce como inserción en profundidad. Este método tiene dos ventajas. Es más eficiente, reemplazando múltiples operaciones más sencillas de creación y asociación con una operación combinada. Además, es atómico, pues o bien toda la operación se realiza correctamente y se crean todos los objetos relacionados, o la operación fracasa y no se crea ninguno.

Como con un Crear básico, el encabezado OData-EntityId de respuesta contiene el URI de la entidad creada. Los URI de las entidades relacionadas creadas no se devuelven. Puede obtener los valores de clave principal de los registros si utiliza el encabezado Prefer: return=representation para que devuelva los valores del registro creado. Más información: Crear con datos devueltos

Por ejemplo, el siguiente cuerpo de solicitud enviado al conjunto de entidades accounts creará un total de cuatro nuevas entidades en el contexto de creación de una cuenta.

Se crea un contacto porque se define como propiedad de objeto de la propiedad de navegación de un solo valor primarycontactid.
Se crea una oportunidad porque se define como un objeto en una matriz que se establece en el valor de una propiedad de navegación valorada como colección opportunity_customer_accounts.
Se crea una tarea porque se define como un objeto en una matriz que se establece en el valor de una propiedad de navegación valorada como colección Opportunity_Tasks.

Nota

Al crear una nueva fila de la tabla, no es posible combinar la creación de la fila con la inserción de una imagen no primaria. Para agregar una imagen no principal, la fila ya debe existir.

Solicitud

POST [Organization URI]/api/data/v9.0/accounts HTTP/1.1
Content-Type: application/json; charset=utf-8
OData-MaxVersion: 4.0
OData-Version: 4.0
Accept: application/json

{
 "name": "Sample Account",
 "primarycontactid":
 {
     "firstname": "John",
     "lastname": "Smith"
 },
 "opportunity_customer_accounts":
 [
  {
      "name": "Opportunity associated to Sample Account",
      "Opportunity_Tasks":
      [
       { "subject": "Task associated to opportunity" }
      ]
  }
 ]
}

Response


HTTP/1.1 204 No Content
OData-Version: 4.0
OData-EntityId: [Organization URI]/api/data/v9.0/accounts(3c6e4b5f-86f6-e411-80dd-00155d2a68cb)

Asociar filas de tabla en la creación

Para asociar nuevas entidades a las entidades existentes cuando se crean debe establecer el valor de las propiedades de navegación mediante la anotación @odata.bind.

El siguiente cuerpo de solicitud enviado al conjunto de entidades de accounts creará una nueva cuenta asociada a un contacto existentes con el valor contactid de 00000000-0000-0000-0000-000000000001 y dos tareas existentes con valores activityid de 00000000-0000-0000-0000-000000000002 y 00000000-0000-0000-0000-000000000003.

Nota

Esta solicitud utiliza el encabezado Prefer: return=representation para que devuelva los valores del registro creado. Más información: Crear con datos devueltos

Solicitud


POST [Organization URI]/api/data/v9.0/accounts?$select=name&$expand=primarycontactid($select=fullname),Account_Tasks($select=subject) HTTP/1.1
Content-Type: application/json; charset=utf-8
OData-MaxVersion: 4.0
OData-Version: 4.0
Accept: application/json
Prefer: return=representation

{
    "name": "Sample Account",
    "primarycontactid@odata.bind": "/contacts(00000000-0000-0000-0000-000000000001)",
    "Account_Tasks@odata.bind": [
        "/tasks(00000000-0000-0000-0000-000000000002)",
        "/tasks(00000000-0000-0000-0000-000000000003)"
    ]
}

Response


HTTP/1.1 201 Created
OData-Version: 4.0
Preference-Applied: return=representation

{
    "@odata.context": "[Organization URI]/api/data/v9.1/$metadata#accounts(name,primarycontactid(fullname),Account_Tasks(subject))/$entity",
    "@odata.etag": "W/\"36236432\"",
    "name": "Sample Account",
    "accountid": "00000000-0000-0000-0000-000000000004",
    "primarycontactid": {
        "@odata.etag": "W/\"28877094\"",
        "fullname": "Yvonne McKay (sample)",
        "contactid": "00000000-0000-0000-0000-000000000001"
    },
    "Account_Tasks": [
        {
            "@odata.etag": "W/\"36236437\"",
            "subject": "Task 1",
            "activityid": "00000000-0000-0000-0000-000000000002"
        },
        {
            "@odata.etag": "W/\"36236440\"",
            "subject": "Task 2",
            "activityid": "00000000-0000-0000-0000-000000000003"
        }
    ]
}

Comprobar registros duplicados

De forma predeterminada, se suprime la detección de duplicados cuando se crean registros mediante la API web. Debe incluir el encabezado MSCRM.SuppressDuplicateDetection: false con la solicitud POST para habilitar la detección de duplicados. La detección de duplicados solo se aplica 1) cuando la organización ha habilitado la detección de duplicados, 2) la entidad está habilitada para la detección de duplicados y 3) se aplican reglas de detección de duplicados activas. Más información: Detectar datos duplicados usando código.

Consulte Detectar duplicados mediante la API web para obtener más información sobre cómo buscar registros duplicados durante la operación de creación.

Crear un nuevo registro a partir de otro registro

Utilice InitializeFrom Function para crear un nuevo registro en el contexto de un registro existente en el que existe una asignación para la relación entre tablas. Para obtener información sobre cómo crear estas asignaciones, consulte:

Nota

Para determinar si se pueden asignar dos entidades, utilice esta consulta:
GET [Organization URI]/api/data/v9.1/entitymaps?$select=sourceentityname,targetentityname&$orderby=sourceentityname

Este es un proceso que consta de dos pasos. La InitializeFrom function no crea el registro, pero devuelve datos que puede utilizar para crear un nuevo registro con los valores de las propiedades especificadas asignados desde el registro original. Combinará los datos de respuesta devueltos en InitializeFrom function con los cambios que desee realizar y luego publique los datos mediante POST para crear el nuevo registro.

El siguiente ejemplo muestra cómo crear un registro de cuenta utilizando los valores de un registro de cuenta existente con el valor accountid igual a 00000000-0000-0000-0000-000000000001.

Paso 1: Obtenga los datos usando InitializeFrom

Solicitud

GET [Organization URI]/api/data/v9.0/InitializeFrom(EntityMoniker=@p1,TargetEntityName=@p2,TargetFieldType=@p3)?@p1={'@odata.id':'accounts(00000000-0000-0000-0000-000000000001)'}&@p2='account'&@p3=Microsoft.Dynamics.CRM.TargetFieldType'ValidForCreate' HTTP/1.1
If-None-Match: null
OData-Version: 4.0
OData-MaxVersion: 4.0
Content-Type: application/json
Accept: application/json

Respuesta

{
    "@odata.context": "[Organization URI]/api/data/v9.0/$metadata#accounts/$entity",
    "@odata.type": "#Microsoft.Dynamics.CRM.account",
    "parentaccountid@odata.bind": "accounts(00000000-0000-0000-0000-000000000001)",
    "transactioncurrencyid@odata.bind": "transactioncurrencies(732e87e1-1d96-e711-80e4-00155db75426)",
    "address1_line1": "123 Maple St.",
    "address1_city": "Seattle",
    "address1_country": "United States of America"
}

Paso 2: Crear el nuevo registro

La respuesta recibida de InitializeFrom function consta de valores de columnas asignadas entre la tabla de origen y la tabla de destino y el GUID del registro primario. La asignación de columnas entre las tablas que tienen una relación de entidad es diferente para tablas diferentes y se puede personalizar, por lo que la respuesta de la solicitud de InitializeFrom function puede variar para organizaciones diferentes.

También pueden establecerse y/o modificarse otros valores de propiedades para el nuevo registro agregándolos en el cuerpo de la solicitud JSON, como se muestra en el siguiente ejemplo.

POST [Organization URI]/api/data/v9.0/accounts HTTP/1.1
Content-Type: application/json; charset=utf-8
OData-MaxVersion: 4.0
OData-Version: 4.0
Accept: application/json

    {
        "@odata.context": "[Organization URI]/api/data/v9.0/$metadata#accounts/$entity",
        "@odata.type": "#Microsoft.Dynamics.CRM.account",
        "parentaccountid@odata.bind": "accounts(00000000-0000-0000-0000-000000000001)",
        "transactioncurrencyid@odata.bind": "transactioncurrencies(732e87e1-1d96-e711-80e4-00155db75426)",
        "name":"Contoso Ltd",
        "numberofemployees":"200",
        "address1_line1":"100 Maple St.",
        "address1_city":"Seattle",
        "address1_country":"United States of America",
        "fax":"73737"
    }
}

Crear documentos en particiones de almacenamiento

Si está creando una gran cantidad de entidades que contienen documentos, puede crear las entidades en particiones de almacenamiento para acelerar el acceso a esos registros de entidad.

Más información: Obtener acceso a los documentos más rápido utilizando particiones de almacenamiento

Consultar también

Ejemplo de operaciones básicas de la API web (C#)
Ejemplo de operaciones básicas de la API web (JavaScript del lado del cliente)
InitializeFrom Function
Realizar operaciones mediante la API web
Componer solicitudes HTTP y administrar errores
Consultar datos utilizando la API web
Recuperar una tabla usando la API web
Actualizar y eliminar tablas mediante la API web
Asociar y anular la asociación de tablas mediante la API web
Usar funciones de la API web
Usar acciones de la API web
Ejecute las operaciones por lotes mediante API web
Suplantar a otro usuario utilizando la API web
Realizar operaciones condicionales mediante la API web

Nota

¿Puede indicarnos sus preferencias de idioma de documentación? Realice una breve encuesta. (tenga en cuenta que esta encuesta está en inglés)

La encuesta durará unos siete minutos. No se recopilan datos personales (declaración de privacidad).

Crear una fila de tabla usando la API web

Crear básico

Crear con datos devueltos

Crea filas de tablas relacionadas en una sola operación

Asociar filas de tabla en la creación

Comprobar registros duplicados

Crear un nuevo registro a partir de otro registro

Paso 1: Obtenga los datos usando InitializeFrom

Paso 2: Crear el nuevo registro

Crear documentos en particiones de almacenamiento

Consultar también

Comentarios