Compartir a través de

Crear una fila de tabla usando la API web

Envíe una POST solicitud al recurso entityset de API web para crear una fila de tabla (registro de entidad) en Microsoft Dataverse. Puede crear varias filas de tabla relacionadas en una sola operación mediante la inserción profunda. También debe saber cómo establecer valores para asociar una nueva fila de tabla a las tablas existentes mediante la @odata.bind anotación .

Nota

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

Creación básica

En este ejemplo se crea un nuevo registro de entidad de cuenta. accounts es el nombre de entidad establecido para account EntityType. El encabezado OData-EntityId de respuesta contiene el URI de la entidad creada.

Solicitud:


POST [Organization URI]/api/data/v9.2/accounts
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.2/accounts(00aa00aa-bb11-cc22-dd33-44ee44ee44ee)

Para crear un registro, debe identificar el nombre del conjunto de entidades válido, los nombres de propiedad y los tipos.

Nota

En Power Apps, al ver una lista de tablas, seleccione Avanzadas>Herramientas. Seleccione Copiar nombre de conjunto para copiar el nombre del conjunto de entidades de la tabla.

También puede seleccionar el vínculo de API a los datos de tabla para ver las 10 filas de datos principales en el explorador. Esta característica funciona mejor cuando tiene una extensión del explorador como formateador JSON instalado que da formato a los datos de texto JSON devueltos.

El nombre del conjunto de entidades no siempre es el mismo que el nombre de la colección o el nombre plural de la tabla. Se almacena en una propiedad independiente denominada EntitySetName.

Cuando crea una nueva fila de tabla, no puede insertar una imagen no primaria al mismo tiempo. Para agregar una imagen no principal, la fila ya debe existir. Obtenga más información sobre las imágenes principales.

Para todas las tablas y atributos del sistema (columnas de la tabla), puede encontrar esta información en el artículo para esa entidad en Referencia del tipo de entidad de la API web. Para tablas o columnas personalizadas, consulte la definición de esa tabla en $Metadata Document CSDL. Más información: Tipos de entidad de la API web.

Establecer el valor de la clave principal

Cada tabla tiene una columna de clave principal de identificador único que puede especificar al crear una fila. En la mayoría de los casos, debe permitir que el sistema establezca este valor automáticamente porque los valores generados por el sistema están optimizados para mejorar el rendimiento.

Dataverse almacena datos de clave primaria en la telemetría para mantener el servicio. Si especifica valores de clave principal personalizados, no use información confidencial en esos valores.

Mediante el uso de tablas elásticas, puede crear registros con valores de clave principal duplicados y valores diferentes partitionid . Sin embargo, este patrón no es compatible con Power Apps basado en modelos o lienzo. Obtenga información sobre cómo establecer el valor de clave principal con tablas elásticas.

Crear con datos devueltos

Puede componer su solicitud POST de manera que devuelva los datos del registro creado 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 $select opción de consulta a la dirección URL del conjunto de entidades. También puede usar $expand para devolver entidades relacionadas.

Las propiedades de navegación con valores de colección anidadas $expand no devuelven datos cuando se utilizan con la return=representation configuración. Para obtener más información, vea Anidado $expand en propiedades de navegación con valores de colección.

Al crear una entidad mediante este método, no se devuelve el OData-EntityId encabezado que contiene el URI al registro creado.

En el ejemplo siguiente se crea una nueva entidad de cuenta y se devuelven los datos solicitados en la respuesta.

Solicitud:


POST [Organization URI]/api/data/v9.2/accounts?$select=name,creditonhold,address1_latitude,description,revenue,accountcategorycode,createdon
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
}

Respuesta:


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.2/$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"
}

Crear múltiples registros en una sola solicitud

Para crear rápidamente varios registros del mismo tipo en una sola solicitud, use la acción CreateMultiple. En el momento de redactar este artículo, la acción CreateMultiple no es compatible con todas las tablas estándar, pero todas las tablas elásticas lo admiten.

Para obtener más información, consulte:

Mediante el uso de tablas estándar, puede crear entidades que se relacionan entre sí definiéndolas como valores de propiedad de navegación. Este patrón se conoce como inserción en profundidad. Este método tiene dos ventajas. Es más eficaz porque reemplaza varias operaciones de creación y asociación más sencillas por una operación atómica combinada. Una operación atómica tiene éxito o falla por completo.

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 mediante el Prefer: return=representation encabezado para que devuelva los valores del registro creado. Obtenga más información sobre cómo crear registros con datos devueltos.

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

  • Se crea un contacto con los valores firstname y lastname porque tú lo defines como propiedad de objeto de una propiedad de navegación de valor único denominada primarycontactid.

  • Se crea una oportunidad relacionada a la cuenta porque se define como un objeto en una matriz al que se le asigna el valor de una propiedad de navegación que tiene valores de colección denominada opportunity_customer_accounts.

  • Se crea una tarea relacionada con la oportunidad porque se define como un objeto de una matriz establecida en el valor de una propiedad de navegación con valores de colección denominada Opportunity_Tasks.

Solicitud:

POST [Organization URI]/api/data/v9.2/accounts
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" }
      ]
  }
 ]
}

Respuesta:


HTTP/1.1 204 No Content
OData-Version: 4.0
OData-EntityId: [Organization URI]/api/data/v9.2/accounts(11bb11bb-cc22-dd33-ee44-55ff55ff55ff)

Asociar filas de tabla al crear

Para asociar nuevos registros a registros existentes al crearlos, use la @odata.bind anotación para establecer el valor de las propiedades de navegación.

El siguiente cuerpo de solicitud enviado al conjunto de entidades accounts crea una cuenta asociada a un contacto existente con el valor contactid00000000-0000-0000-0000-000000000001 y dos tareas existentes con los valores activityid00000000-0000-0000-0000-000000000002 y 00000000-0000-0000-0000-000000000003.

Esta solicitud usa el Prefer: return=representation encabezado para que devuelva los valores del registro creado. Para obtener más información, consulte Creación con datos devueltos.

Solicitud:


POST [Organization URI]/api/data/v9.2/accounts?$select=name&$expand=primarycontactid($select=fullname),Account_Tasks($select=subject)
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)"
    ]
}

Respuesta:


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

{
    "@odata.context": "[Organization URI]/api/data/v9.2/$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, el sistema suprime la detección de duplicados al crear registros. Para habilitar la detección de duplicados, incluya el encabezado MSCRM.SuppressDuplicateDetection: false con su solicitud POST. Detección de duplicados solo se aplica cuando se cumplen las siguientes condiciones:

  • La organización ha habilitado la detección de duplicados.
  • La entidad tiene habilitada la detección de duplicados.
  • Se aplican las reglas de detección de duplicados activas.

Para obtener más información, consulte:

Crear un registro a partir de otro registro

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

Para determinar si dos entidades se pueden mapear, utilice la siguiente consulta:

GET [Organization URI]/api/data/v9.2/entitymaps?
$select=sourceentityname,targetentityname&$orderby=sourceentityname

La creación de un nuevo registro a partir de otro registro es un proceso de dos pasos. En primer lugar, use la función InitializeFrom para devolver los valores de las propiedades mapeados desde el registro original. A continuación, combine los datos de respuesta devueltos en la función InitializeFrom con los cambios que desee realizar y POST los datos para crear el registro.

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

Paso 1: Obtener los datos mediante InitializeFrom

Solicitud:

GET [Organization URI]/api/data/v9.2/InitializeFrom(EntityMoniker=@p1,TargetEntityName=@p2,TargetFieldType=@p3)?
@p1={'@odata.id':'accounts(00000000-0000-0000-0000-000000000001)'}&
@p2='account'&@p3=Microsoft.Dynamics.CRM.TargetFieldType'ValidForCreate'
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.2/$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 que recibe de InitializeFrom incluye valores de columnas mapeadas entre la tabla de origen y la tabla de destino, y el GUID del registro padre. La asignación de columnas entre tablas que tienen una relación difiere para distintas tablas y organizaciones, por lo que la respuesta de InitializeFrom varía.

Puede establecer o modificar otros valores de propiedad para el nuevo registro agregándolos en el cuerpo de la solicitud JSON, como se muestra en el ejemplo siguiente:

POST [Organization URI]/api/data/v9.2/accounts
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.2/$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 crea un gran número de registros para tablas elásticas, cree las entidades en particiones de almacenamiento para acelerar el acceso a esos registros de entidades.

Obtenga información sobre cómo crear registros en una tabla elástica.

Consulte 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)
Función InitializeFrom
Realizar operaciones mediante la API web
Componer solicitudes HTTP y administrar errores
Consultar datos utilizando la API web
Recuperar una fila de tabla usando la API web
Actualizar y eliminar filas de tablas usando la API web
Asociar y anular la asociación de filas de tabla 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

  • Last updated on