Criar uma entidade usando a API da Web

Artigo
10/31/2017

Publicado: janeiro de 2017

Aplicável a: Dynamics 365 (online), Dynamics 365 (on-premises), Dynamics CRM 2016, Dynamics CRM Online

Use uma solicitação POST para enviar dados para criar uma entidade. É possível criar várias entidades relacionadas em uma única operação usando “inserção profunda”. Também é necessário saber como definir valores para associar uma nova entidade a entidades existentes usando a anotação de @odata.bind.

Observação

Para obter informações sobre como criar e atualizar os metadados da entidade usando A API, consulte Criar e atualizar definições de entidade usando API da Web.

Neste tópico

Criar básico

Criar entidades relacionadas em uma operação

Associar entidades ao criar

Criar com dados retornados

Criar básico

Esse exemplo cria uma entidade de conta. O cabeçalho de OData-EntityId de resposta contém o URI da entidade criada.

Solicitação

POST cc_WebAPI_ServiceURI/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
}

Resposta

HTTP/1.1 204 No Content
OData-Version: 4.0
OData-EntityId: cc_WebAPI_ServiceURI/accounts(7eb682f1-ca75-e511-80d4-00155d2a68d1)

Para criar uma entidade, você deve identificar os nomes e tipos válidos da propriedade. Para todas as entidades e atributos do sistema, você pode encontrar essas informações no tópico dessa entidade na Web API EntityType Reference. Para entidades ou atributos personalizados, consulte a definição dessa entidade no d80cfb87-d4f1-4c75-bcc8-4f54d1351e26#bkmk_csdl.Para obter mais informações:d80cfb87-d4f1-4c75-bcc8-4f54d1351e26#bkmk_entityTypes

Criar entidades relacionadas em uma operação

Você pode criar entidades relacionadas umas às outras definindo-as como valores de propriedades de navegação. Isso é conhecido como inserção profunda.

Assim como um criar básico, o cabeçalho de OData-EntityId de resposta contém o Uri da entidade criada. Os URIs das entidades relacionadas criadas não são retornados.

Por exemplo, o corpo da seguinte solicitação publicada no conjunto de entidades da Account criará um total de quatro novas entidades no contexto de criação de uma conta.

Um contato é criado porque ele é definido como uma propriedade de objeto da primarycontactid de propriedade de navegação de valor único.
Uma oportunidade é criada porque ela é definida como um objeto em uma matriz que é definida como o valor de uma opportunity_customer_accounts de propriedade de navegação de valor de conjunto.
Uma tarefa é criada porque ela é definida como um objeto em uma matriz que é definida como o valor de uma Opportunity_Tasks de propriedade de navegação de valor de conjunto.

Solicitação

POST cc_WebAPI_ServiceURI/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" }
      ]
  }
 ]
}

Resposta

HTTP/1.1 204 No Content
OData-Version: 4.0
OData-EntityId: cc_WebAPI_ServiceURI/accounts(3c6e4b5f-86f6-e411-80dd-00155d2a68cb)

Associar entidades ao criar

Para associar novas entidades a entidades existentes quando elas são criadas, você deve definir o valor das propriedades de navegação de valor único usando a anotação de @odata.bind.

O corpo da seguinte solicitação publicada no conjunto de entidades das contas criará uma conta associada a um contato existente com o valor da contactid de 00000000-0000-0000-0000-000000000001.

Solicitação

POST cc_WebAPI_ServiceURI/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@odata.bind":"/contacts(00000000-0000-0000-0000-000000000001)"
}

Resposta

HTTP/1.1 204 No Content
OData-Version: 4.0
OData-EntityId: cc_WebAPI_ServiceURI/accounts(00000000-0000-0000-0000-000000000002)

Observação

Associar entidades dessa forma com uma propriedade de navegação de valor de conjunto não é compatível com a API da Web.

Criar com dados retornados

Observação

Esse recurso foi adicionado no Atualização de dezembro de 2016 para Dynamics 365 (online e local).

É possível redigir sua solicitação POST de modo que os dados do registro criado seja retornados com um status 201 (Created). Para atingir seu resultado, você precisa usar a preferência return=representation nos cabeçalhos da solicitação.

Para controlar quais propriedades serão retornadas, acrescente a opção de consulta $select à URL para o conjunto de entidades. A opção de consulta $expand será ignorada se for usada.

Quando uma entidade é criada dessa maneira, o cabeçalho OData-EntityId com o URI para o registro criado não será retornado.

Este exemplo cria uma nova entidade de conta e retorna os dados solicitados na resposta.

Solicitação

POST cc_WebAPI_ServiceURI/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
}

Resposta

HTTP/1.1 201 Created
Content-Type: application/json; odata.metadata=minimal
Preference-Applied: return=representation
OData-Version: 4.0

{
    "@odata.context": "cc_WebAPI_ServiceURI/$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"
}

Confira Também

Amostra de operações básicas API da Web (C#)
Exemplo de operações básicas da API Web (JavaScript do lado do cliente)
Executar operações usando A API
Compor solicitações de HTTP e lidar com erros
Consultar dados usando a API da Web
Recuperar uma entidade usando a API Web
Atualizar e excluir entidades que usam a API Web
Associar e desassociar entidades usando a API Web
Usar funções da API Web
Use ações API da Web
Executar operações em lote usando a API da WEB
Representar outro usuário usando API da Web
Executar operações condicionais usando A API

Microsoft Dynamics 365

Compartilhar via

Criar uma entidade usando a API da Web

Neste tópico

Criar básico

Criar entidades relacionadas em uma operação

Associar entidades ao criar

Criar com dados retornados

Confira Também

Recursos adicionais