Criar uma linha de tabela usando a API Web

Envie uma POST solicitação para o recurso de conjunto de entidades da API Web para criar uma linha de tabela (registro de entidade) no Microsoft Dataverse. Você pode criar várias linhas de tabela relacionadas em uma única operação usando inserção profunda. Você também precisa saber como definir valores para associar uma nova linha de tabela a tabelas existentes usando a @odata.bind anotação.

Criação básica

Este exemplo cria um novo registro de entidade de conta. accounts é o nome do conjunto de entidades para a conta EntityType. O cabeçalho de resposta OData-EntityId contém o URI da entidade criada.

Solicitação:

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
}

Resposta:

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 criar um registro, você deve identificar o nome, os nomes de propriedade e os tipos válidos do conjunto de entidades.

Para todas as tabelas e atributos do sistema (colunas de tabela), você pode encontrar essas informações no artigo para essa entidade na Referência de Tipo de Entidade da API Web. Para tabelas ou colunas personalizadas, consulte a definição dessa tabela no documento $metadata CSDL. Mais informações: EntityTypes da API Web.

Definindo o valor da chave primária

Cada tabela tem uma coluna de chave primária de identificador exclusivo que você pode especificar ao criar uma linha. Na maioria dos casos, você deve permitir que o sistema defina esse valor para você porque os valores gerados pelo sistema são otimizados para melhor desempenho.

O Dataverse armazena dados de chave primária na telemetria para ajudar a manter o serviço. Se você especificar valores de chave primária personalizados, não use informações confidenciais nesses valores.

Usando tabelas elásticas, você pode criar registros com valores de chave primária duplicados e valores diferentes partitionid . No entanto, esse padrão não é compatível com o Power Apps controlado por modelo ou tela. Saiba mais sobre como definir o valor da chave primária com tabelas elásticas.

Criar com os dados retornados

Você pode compor sua POST solicitação para que ela retorne dados do registro criado com um status de 201 (Created). Para obter esse resultado, você deve usar a return=representation preferência nos cabeçalhos de solicitação.

Para controlar quais propriedades são retornadas, acrescente a opção $select de consulta à URL do conjunto de entidades. Você também pode usar $expand para retornar entidades relacionadas.

O recurso aninhado $expand em propriedades de navegação com valor de coleção não retorna dados quando usado com a preferência return=representation. Para obter mais informações, consulte Aninhado $expand em propriedades de navegação com valor de coleção.

Quando você cria uma entidade usando esse método, o OData-EntityId cabeçalho que contém o URI para o registro criado não é retornado.

O exemplo a seguir cria uma nova entidade de conta e retorna os dados solicitados na resposta.

Solicitação:

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
}

Resposta:

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

Criar vários registros em uma única solicitação

Para criar rapidamente vários registros do mesmo tipo em uma única solicitação, use a ação CreateMultiple. Na época da redação, a ação CreateMultiple não é suportada por todas as tabelas padrão, mas todas as tabelas elásticas a suportam.

Para obter mais informações, consulte:

• Mensagens de operação em massa
• Exemplo: SDK para .NET Uso de operações em lote
• Usar CreateMultiple com tabelas elásticas

Criar linhas de tabela relacionadas em uma operação

Usando tabelas padrão, você pode criar entidades que se relacionam entre si definindo-as como valores de propriedade de navegação. Esse padrão é conhecido como inserção profunda. Essa abordagem tem duas vantagens. É mais eficiente porque substitui várias operações de criação e associação mais simples por uma operação atômica combinada. Uma operação atômica é bem-sucedida ou falha totalmente.

Assim como acontece com uma criação básica, o cabeçalho de resposta OData-EntityId contém o URI da entidade criada. As URIs das entidades relacionadas criadas não são retornadas. Você pode obter os valores de chave primária dos registros usando o Prefer: return=representation cabeçalho para que ele retorne os valores do registro criado. Saiba mais sobre como criar registros com dados retornados.

Por exemplo, o corpo da solicitação a seguir postado no accounts conjunto de entidades cria um total de quatro registros no contexto de criação de uma conta.

• Um contato é criado com os valores firstname e lastname porque você define isso como uma propriedade de objeto da propriedade de navegação de valor único chamada primarycontactid.

• Uma oportunidade relacionada à conta é criada porque você a define como um objeto em uma matriz que é definida para o valor de uma propriedade de navegação com valor de coleção chamada opportunity_customer_accounts.

• Uma tarefa relacionada à oportunidade é criada porque você a define como um objeto em uma matriz definida como o valor de uma propriedade de navegação com valor de coleção chamada Opportunity_Tasks.

Solicitação:

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

Resposta:

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

Associar linhas de tabela ao criar

Para associar novos registros a registros existentes ao criá-los, use a @odata.bind anotação para definir o valor das propriedades de navegação.

O corpo da solicitação a seguir postado no accounts conjunto de entidades cria uma conta associada a um contato existente com o contactid valor de 00000000-0000-0000-0000-000000000001 e duas tarefas existentes com activityid valores de 00000000-0000-0000-0000-000000000002 e 00000000-0000-0000-0000-000000000003.

Essa solicitação usa o Prefer: return=representation cabeçalho para que ele retorne os valores do registro criado. Para obter mais informações, consulte Criar com os dados retornados.

Solicitação:

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

Resposta:

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

Verificar se há registros duplicados

Por padrão, o sistema suprime a detecção duplicada quando você cria registros. Para habilitar a detecção de duplicados, inclua o cabeçalho MSCRM.SuppressDuplicateDetection: false com sua solicitação POST. A detecção duplicada só se aplica quando as seguintes condições são verdadeiras:

• A organização habilitou a detecção de duplicados.
• A entidade está habilitada para detecção de duplicados.
• As regras de detecção de duplicatas ativas são aplicadas.

Para obter mais informações, consulte:

• Detectar dados duplicados usando código
• Detectar dados duplicados usando a API Web
• Detectar dados duplicados usando o SDK para .NET

Criar um registro de outro registro

Use a função InitializeFrom para criar um registro no contexto de um registro existente em que a relação entre as tabelas é mapeada. Para obter informações sobre como criar esses mapeamentos, consulte:

• Mapear colunas da tabela
• Personalizar mapeamentos de tabela e coluna

Para determinar se duas entidades podem ser mapeadas, use a seguinte consulta:

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

Criar um novo registro de outro registro é um processo de duas etapas. Primeiro, use a função InitializeFrom para retornar valores de propriedade mapeados do registro original. Em seguida, combine os dados de resposta retornados na função InitializeFrom com as alterações que você deseja fazer e POST os dados para criar o registro.

O exemplo a seguir mostra como criar um registro de conta usando os valores de um registro de conta existente com um accountid valor igual a 00000000-0000-0000-0000-000000000001.

Etapa 1: Obter os dados usando InitializeFrom

Solicitação:

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

Resposta:

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

Etapa 2: Criar o novo registro

A resposta que você recebe de InitializeFrom inclui os valores das colunas mapeadas entre a tabela de origem e a tabela de destino, e o GUID do registro pai. O mapeamento de coluna entre tabelas que têm uma relação difere para diferentes tabelas e organizações, por isso a resposta de InitializeFrom varia.

Você pode definir ou modificar outros valores de propriedade para o novo registro adicionando-os no corpo da solicitação JSON, conforme mostrado no exemplo a seguir:

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

Criar documentos em partições de armazenamento

Se você criar um grande número de registros para tabelas elásticas, crie as entidades em partições de armazenamento para acelerar o acesso a esses registros de entidade.

Saiba mais sobre como criar registros em uma tabela elástica.

Consulte também

Exemplo de operações básicas da API Web (C#)
Exemplo de operações básicas da API Web (JavaScript do lado do cliente)
Função InitializeFrom
Executar operações usando a API Web
Redigir solicitações HTTP e manipular erros
Consultar dados usando a API Web
Recuperar uma linha de tabela usando a API Web
Atualizar e excluir linhas de tabela usando a API Web
Associar e desassociar linhas de tabela usando a API Web
Usar funções de API Web
Use ações API da Web
Executar operações em lote usando a API Web
Representar outro usuário usando a API Web
Executar operações condicionais usando a API Web