Crear una fila de tabla usando la API web

  • Artículo

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. 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.0/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.0/accounts(7eb682f1-ca75-e511-80d4-00155d2a68d1)

Para crear un nuevo registro de entidad debe identificar el nombre del conjunto de ntidades, y los nombres y los tipos de propiedad válidos. 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: EntityTypes 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 lo establezca automáticamente porque los valores generados por el sistema se optimizan para el máximo rendimiento.

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

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.

Las propiedades de navegación de $expand anidado con valor de colección no devolverán datos cuando se usan con la preferencia return=representation. Más información: $expand anidado en propiedades de navegación valorada en una colección

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

Crear múltiples registros en una sola solicitud

La forma más rápida de crear varios registros del mismo tipo en una sola solicitud es utilizar la acción CreateMultiple. En el momento de escribir este artículo, la acción CreateMultiple. No todas las tablas estándar admiten esta acción, pero todas las tablas elásticas sí.

Más información:

Con las tablas estándar, puede crear entidades relacionadas entre sí definiéndolas como valores de propiedades de navegación. Este patrón se conoce como inserción en profundidad. Este método tiene dos ventajas. Es más eficiente, porque reemplaza múltiples operaciones más sencillas de creación y asociación con una operación atómica. 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 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 crea un total de cuatro registros en el contexto de creación de una cuenta.

  • Se crea un contacto porque se define como una propiedad de objeto de la propiedad de navegación de valor único primarycontactid.

  • Se crea una oportunidad porque se define como un objeto dentro de 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

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.

Solicitud:

POST [Organization URI]/api/data/v9.0/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.0/accounts(3c6e4b5f-86f6-e411-80dd-00155d2a68cb)

Asociar filas de tabla en la creación

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

El siguiente cuerpo de solicitud enviado al conjunto de entidades de accounts crea 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.

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)
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.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. Para hbilitar la detección de duplicados, incluya el encabezado MSCRM.SuppressDuplicateDetection: false con la solicitud POST para habilitar la detección de duplicados. 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.

Más información:

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 tablas. Para obtener información sobre cómo crear estas asignaciones, consulte:

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

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

La creación de un nuevo registro a partir de otro registro es un proceso de dos pasos. Primero, use la función InitializeFrom para devolver valores de propiedad asignados desde el registro original. Luego, combien los datos de respuesta devueltos en InitializeFrom function con los cambios que desee realizar y luego publique los datos mediante POST para crear el 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 con 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'
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
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 registros para tablas elásticas, puede crear las entidades en particiones de almacenamiento para acelerar el acceso a esos registros de entidad.

Más información: Crear un registro 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

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).