Use ações API da Web

Use ações de API Web para executar operações reutilizáveis que têm efeitos colaterais no Microsoft Dataverse. Envie uma solicitação POST com ações listadas Web API Action Reference para modificar dados, disparar a lógica de negócios ou invocar processos personalizados. Você também pode definir ações personalizadas. Para obter mais informações, consulte Criar suas próprias mensagens.

As ações são definidas no documento $metadata CSDL. Consulte Ações de API Web para obter mais informações.

Ações não associadas

O XML a seguir mostra a definição da ação Merge representada no documento de serviço $metadata.

<Action Name="Merge">
   <Parameter Name="Target" 
      Type="mscrm.crmbaseentity" 
      Nullable="false" />
   <Parameter Name="Subordinate" 
      Type="mscrm.crmbaseentity" 
      Nullable="false" />
   <Parameter Name="UpdateContent" 
      Type="mscrm.crmbaseentity" />
   <Parameter Name="PerformParentingChecks" 
      Type="Edm.Boolean" 
      Nullable="false" />
</Action>

A Merge ação corresponde à MergeRequest classe quando você usa o SDK para .NET. Use essa ação para mesclar um par de registros duplicados. Essa ação não inclui um valor retornado. Se for bem-sucedida, a operação será concluída.

O exemplo a seguir mostra a solicitação HTTP e a resposta para chamar a ação Merge para dois registros de conta.

Solicitação:

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

{
  "Target": {
    "@odata.type": "Microsoft.Dynamics.CRM.account",
    "accountid": "cc1e2c4a-e577-ec11-8d21-000d3a554dcd"
  },
  "Subordinate": {
    "@odata.type": "Microsoft.Dynamics.CRM.account",
    "accountid": "e408fa45-3a70-ec11-8943-00224823561e"
  },
  "PerformParentingChecks": false
}

Resposta:

HTTP/1.1 204 No Content
OData-Version: 4.0

Para obter mais informações, consulte Mesclar linhas de tabela usando a API Web.

Ações vinculadas

Você pode associar uma ação a uma entidade ou a uma coleção de entidades. Associar uma ação a uma entidade é mais comum.

No documento $metadata CSDL, um Action elemento que representa uma ação associada tem um IsBound atributo definido como true. O primeiro Parameter elemento definido dentro da ação representa a entidade à qual a operação está associada. Quando o Type atributo do parâmetro é uma coleção, a operação é associada a uma coleção de entidades.

Ao invocar uma função associada, inclua o nome completo da função, incluindo o Microsoft.Dynamics.CRM namespace. Se você não incluir o nome completo, receberá o seguinte erro: Status Code:400 Request message has unresolved parameters.

Ações associadas a uma tabela

O exemplo a seguir mostra a definição da ação AddToQueue e do tipo complexo AddToQueueResponse no CSDL como uma ação vinculada a uma entidade.

<ComplexType Name="AddToQueueResponse">
     <Property Name="QueueItemId" 
        Type="Edm.Guid" 
        Nullable="false" />
</ComplexType>
 <Action Name="AddToQueue" 
    IsBound="true">
  <Parameter Name="entity" 
    Type="mscrm.queue" 
    Nullable="false" />
  <Parameter Name="Target" 
    Type="mscrm.crmbaseentity" 
    Nullable="false" />
  <Parameter Name="SourceQueue" 
    Type="mscrm.queue" />
  <Parameter Name="QueueItemProperties" 
    Type="mscrm.queueitem" />
  <ReturnType Type="mscrm.AddToQueueResponse" 
    Nullable="false" />
</Action>

Essa ação associada à entidade é equivalente ao AddToQueueRequest usado pelo SDK para .NET. Na API Web, essa ação está vinculada ao queue tipo de entidade que representa a propriedade AddToQueueRequestDestinationQueueId.

Essa ação aceita vários outros parâmetros e retorna um AddToQueueResponse tipo complexo correspondente ao AddToQueueResponse retornado pelo SDK para .NET. Quando uma ação retorna um tipo complexo, a definição do tipo complexo aparece diretamente acima da ação no CSDL.

Você deve invocar uma ação associada a uma entidade usando um URI para definir o primeiro valor de parâmetro. Você não pode defini-lo como um valor de parâmetro nomeado.

O exemplo a seguir mostra como usar a ação AddToQueue para adicionar uma letra a uma fila. Como o tipo do tipo de Target parâmetro não é específico (mscrm.crmbaseentity), você deve declarar explicitamente o tipo do objeto usando o @odata.type valor da propriedade do nome completo da entidade, incluindo o Microsoft.Dynamics.CRM namespace. Nesse caso, Microsoft.Dynamics.CRM.letter. Para obter mais informações, consulte Especificar tipo de parâmetro de entidade.

Solicitação:

POST [Organization URI]/api/data/v9.2/queues(56ae8258-4878-e511-80d4-00155d2a68d1)/Microsoft.Dynamics.CRM.AddToQueue HTTP/1.1
Accept: application/json
Content-Type: application/json; charset=utf-8
OData-MaxVersion: 4.0
OData-Version: 4.0

{
 "Target": {
  "activityid": "59ae8258-4878-e511-80d4-00155d2a68d1",
  "@odata.type": "Microsoft.Dynamics.CRM.letter"
 }
}

Resposta:

HTTP/1.1 200 OK
Content-Type: application/json; odata.metadata=minimal
OData-Version: 4.0

{
 "@odata.context": "[Organization URI]/api/data/v9.2/$metadata#Microsoft.Dynamics.CRM.AddToQueueResponse",
 "QueueItemId": "5aae8258-4878-e511-80d4-00155d2a68d1"
}

Ações associadas a uma coleção de tabelas

É menos comum encontrar ações associadas a uma coleção de entidades. A lista a seguir inclui algumas ações que você pode encontrar:

Como exemplo de uma ação associada a uma coleção de entidades, a definição a seguir mostra a ExportTranslation ação representada no $metadata CSDL:

<ComplexType Name="ExportTranslationResponse">
   <Property Name="ExportTranslationFile" 
    Type="Edm.Binary" />
</ComplexType>
<Action Name="ExportTranslation" 
    IsBound="true">
   <Parameter Name="entityset" 
    Type="Collection(mscrm.solution)" 
    Nullable="false" />
   <Parameter Name="SolutionName" 
    Type="Edm.String" 
    Nullable="false" 
    Unicode="false" />
   <ReturnType Type="mscrm.ExportTranslationResponse" 
    Nullable="false" />
</Action>

Essa ação associada à coleção de entidades é equivalente à ExportTranslationRequest usada pelo SDK para .NET. Na API Web, essa ação está associada ao solution tipo de entidade. Mas, em vez de passar um valor para a solicitação, a restrição de associação de coleção de entidades exige que o URI da solicitação inclua o caminho para o conjunto de entidades especificado.

O exemplo a seguir mostra como usar a ação ExportTranslation , que exporta um arquivo binário contendo dados sobre valores de cadeia de caracteres localizáveis que você pode atualizar para modificar ou adicionar valores localizáveis. Observe como a ação associada à coleção de entidades vem após o nome do conjunto de entidades para a entidade da solução: solutions.

Solicitação:

POST [Organization URI]/api/data/v9.2/solutions/Microsoft.Dynamics.CRM.ExportTranslation HTTP/1.1
Accept: application/json
Content-Type: application/json
OData-MaxVersion: 4.0
OData-Version: 4.0

{
    "SolutionName":"MySolution"
}

Resposta:

HTTP/1.1 200 OK
Content-Type: application/json; odata.metadata=minimal
OData-Version: 4.0

{
    "@odata.context": "[Organization URI]/api/data/v9.2/$metadata#Microsoft.Dynamics.CRM.ExportTranslationResponse",
    "ExportTranslationFile": "[Binary data Removed for brevity]"
}

Usar uma ação personalizada

Uma ação personalizada pode ser uma API personalizada ou uma ação de processo personalizada. Cada tipo de ação personalizada tem uma operação correspondente que você pode usar. Para uma API personalizada, a operação pode ser uma função. Para saber mais, confira Criar suas próprias mensagens.

O exemplo a seguir mostra uma ação de processo personalizada.

Exemplo de ação personalizada: adicionar uma anotação a um contato

Suponha que você queira criar uma ação personalizada que adicione uma nova anotação a um contato específico. Você pode criar uma ação personalizada associada à entidade de contato com as propriedades a seguir.

Argumentos de processo

Etapas

Depois de publicar e ativar a ação personalizada, você verá essa nova ação definida ao baixar o CSDL.

<Action Name="new_AddNoteToContact" 
    IsBound="true">
  <Parameter Name="entity" 
    Type="mscrm.contact" 
    Nullable="false" />
  <Parameter Name="NoteTitle" 
    Type="Edm.String" 
    Nullable="false" 
    Unicode="false" />
  <Parameter Name="NoteText" 
    Type="Edm.String" 
    Nullable="false" 
    Unicode="false" />
  <ReturnType Type="mscrm.annotation" 
    Nullable="false" />
</Action>

A solicitação HTTP e a resposta a seguir mostram como chamar a ação personalizada e a resposta retornada se bem-sucedida.

Solicitação:

POST [Organization URI]/api/data/v9.2/contacts(94d8c461-a27a-e511-80d2-00155d2a68d2)/Microsoft.Dynamics.CRM.new_AddNoteToContact HTTP/1.1
Accept: application/json
Content-Type: application/json; charset=utf-8
OData-MaxVersion: 4.0
OData-Version: 4.0

{
 "NoteTitle": "New Note Title",
 "NoteText": "This is the text of the note"
}

Resposta:

HTTP/1.1 200 OK
Content-Type: application/json; odata.metadata=minimal
OData-Version: 4.0

{
 "@odata.context": "[Organization URI]/api/data/v9.2/$metadata#annotations/$entity",
 "annotationid": "9ad8c461-a27a-e511-80d2-00155d2a68d2"
}

Especificar o parâmetro de tipo de tabela

Quando uma ação exigir uma entidade como um parâmetro e o tipo de entidade for ambíguo, use a @odata.type propriedade para especificar o tipo de entidade. O valor dessa propriedade é o nome totalmente qualificado da entidade, que segue este padrão: Microsoft.Dynamics.CRM.+<nome> lógico da entidade.

Conforme mostrado na seção Ações vinculadas, o parâmetro Target da ação AddToQueue é uma atividade. Mas como todas as atividades herdam do activitypointer tipo de entidade, você deve incluir a seguinte propriedade na entidade JSON para especificar que o tipo de entidade é uma letra: "@odata.type": "Microsoft.Dynamics.CRM.letter".

Dois outros exemplos são AddMembersTeam e RemoveMembersTeam ações porque o Members parâmetro é uma coleção do tipo de entidade systemuser, que herda sua ownerid chave primária do tipo de entidade principal. Ao passar o JSON abaixo para representar um único systemuser na coleção, fica evidente que a entidade é um systemuser e não um tipo de entidade team, que também herda do tipo de entidade principal.

{
 "Members": [{
  "@odata.type": "Microsoft.Dynamics.CRM.systemuser",
  "ownerid": "5dbf5efc-4507-e611-80de-5065f38a7b01"
 }]
}

Se você não especificar o tipo de entidade nessa situação, poderá obter o seguinte erro: "EdmEntityObject passed should have the key property value set.".

Consulte também

Ações de API Web
Exemplo de ações e funções da API Web (C#)
Exemplo de ações e funções da API Web (JavaScript do lado do cliente)
Executar operações usando a API Web
Redigir solicitações Http e manipular erros
Consultar dados usando a API Web
Criar uma linha de tabela 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
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