Use ações API da Web

Publicado: janeiro de 2017

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

Ação e as funções representam operações reutilizáveis que você pode realizar usando a API da Web. Use uma solicitação POST com ações listadas em Web API Action Reference para realizar operações que apresentam efeitos colaterais. Você também pode definir as ações personalizadas e elas estarão disponíveis para você usar.

Neste tópico

Ações desvinculadas

Ações vinculadas

Usar uma ação personalizada

Especifique o tipo de parâmetro da entidade

Ações desvinculadas

Ações são definidas em d80cfb87-d4f1-4c75-bcc8-4f54d1351e26#bkmk_csdl. Como exemplo, o que vem a seguir é a definição de WinOpportunity Action representado no CSDL.

<Action Name="WinOpportunity">
  <Parameter Name="OpportunityClose" Type="mscrm.opportunityclose" Nullable="false" />
  <Parameter Name="Status" Type="Edm.Int32" Nullable="false" />
</Action>

A ação WinOpportunity corresponde ao WinOpportunityRequest usando o serviço da organização. Use esta ação para definir o estado de uma oportunidade para Ganha e crie uma opportunityclose EntityType para registrar um evento. Esta ação não inclui um valor de retorno. Se tiver êxito, a operação é concluída.

O parâmetro OpportunityClose exige uma representação de JSON da entidade opportunityclose para criar na operação. Esta entidade deve estar relacionada à oportunidade que emite propriedade de navegação de valor único de opportunityid. Em JSON está definido usando a anotação @odata.bind como explicado em Associar entidades ao criar.

O parâmetro Status deve ser definido para o estado de opportunity quando for fechado. Você pode encontrar o valor padrão disso na propriedade opportunity EntityTypestatuscode. A opção Ganha tem um valor de três. Você pode se perguntar: por que é necessário definir esse valor quando há somente uma opção de razão do status que representa Ganha? A razão é porque você pode definir opções de estado personalizado para representar um ganho, como Ganho Grande ou Ganho Pequeno, para que o valor possa potencialmente ser diferente de 3 nesta situação.

O exemplo a seguir é a solicitação HTTP e resposta para chamar a ação WinOpportunity de uma oportunidade com um valor opportunityid de b3828ac8-917a-e511-80d2-00155d2a68d2.

• Solicitação

  POST cc_WebAPI_ServiceURI/WinOpportunity HTTP/1.1
  Accept: application/json
  Content-Type: application/json; charset=utf-8
  OData-MaxVersion: 4.0
  OData-Version: 4.0
  
  {
   "Status": 3,
   "OpportunityClose": {
    "subject": "Won Opportunity",
    "opportunityid@odata.bind": "cc_WebAPI_ServiceURI/opportunities(b3828ac8-917a-e511-80d2-00155d2a68d2)"
   }
  }
  

• Resposta

  HTTP/1.1 204 No Content
  OData-Version: 4.0
  

Ações vinculadas

No d80cfb87-d4f1-4c75-bcc8-4f54d1351e26#bkmk_csdl, quando um elemento Action representa uma ação vinculada, tem um atributo IsBound com o valor true. O primeiro elemento Parâmetro definido dentro da ação representa a entidade à qual a operação está associada. Quando o atributo Type do parâmetro é uma coleção, a operação está associada a uma coleção de entidades. Como um exemplo, o que vem a seguir é a definição de AddToQueue Action representado no CSDL:

 <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 associação é equivalente ao AddToQueueRequest usado pelo serviço da organização. Na API da Web esta ação está associada ao queue EntityType que representa o AddToQueueRequest. Propriedade DestinationQueueId. Esta ação aceita diversos parâmetros adicionais e devolve um AddToQueueResponse ComplexType correspondente ao AddToQueueResponse devolvido pelo serviço da organização. Quando uma ação retorna um tipo complexo, a definição do tipo complexo aparecerá diretamente acima da ação no CSDL.

Uma ação vinculada deve ser invocada usando um URI para definir o primeiro valor de parâmetro. Não é possível defini-la como um valor de parâmetro nomeado.

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

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

• Solicitação

  POST cc_WebAPI_ServiceURI/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": "cc_WebAPI_ServiceURI/$metadata#Microsoft.Dynamics.CRM.AddToQueueResponse",
   "QueueItemId": "5aae8258-4878-e511-80d4-00155d2a68d1"
  }
  

Usar uma ação personalizada

Se você definir as ações personalizadas de sua organização ou solução, elas também serão incluídas no d80cfb87-d4f1-4c75-bcc8-4f54d1351e26#bkmk_csdl. Para obter informações sobre como criar ações usando as ferramentas de personalização no aplicativo, consulte o tópico TechNetAções. Para obter informações sobre como criar e usar suas próprias ações personalizadas, consulte Criar suas próprias ações.

Independentemente se as operações incluídas em sua ação personalizada apresentam efeitos colaterais, elas podem modificar potencialmente e, portanto são consideradas ações em vez de funções. Não existe uma maneira de criar uma função personalizada.

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

Digamos que você deseja criar uma ação personalizada que irá adicionar uma nova anotação a um contato específico. Você pode criar uma ação vinculada personalizada para a entidade do contato com as propriedades a seguir.

Argumentos do Processo

Etapas

Depois que você publicar e ativar a ação personalizada, quando você baixar o CSDL, você encontrará esta nova ação definida.

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

As solicitações a seguir de HTTP e resposta mostram como chamar uma ação personalizada e se a resposta que ela devolve é bem-sucedida.

• Solicitação

  POST cc_WebAPI_ServiceURI/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": "cc_WebAPI_ServiceURI/$metadata#annotations/$entity",
   "annotationid": "9ad8c461-a27a-e511-80d2-00155d2a68d2"
  }
  

Especifique o tipo de parâmetro da entidade

Quando uma ação exigir uma entidade como um parâmetro e o tipo de entidade for ambíguo, use a propriedade @odata.type para especificar o tipo de entidade. O valor desta 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 acima, o parâmetro do Target para a AddToQueue Action é uma atividade. Mas como todas as atividades são herdadas de activitypointer EntityType, é necessário incluir a seguinte propriedade na entidade JSON para especificar que o tipo de entidade é uma letra: "@odata.type": "Microsoft.Dynamics.CRM.letter".

Os dois outros exemplos são AddMembersTeam Action e RemoveMembersTeam Action porque o parâmetro Members é um conjunto de systemuser EntityType que herda sua chave primária de ownerid do principal EntityType. Se você transmite o seguinte JSON para representar um usuário único do sistema no conjunto, é claro que a entidade é um usuário do sistema e não um team EntityType, que também é herdado 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 nesta situação, você poderá receber a seguinte mensagem de erro: "EdmEntityObject passed should have the key property value set.".

Confira Também

Exemplo de funções API da Web e ações (C#)
Funções da API Web e Amostra de ações (Javascript do cliente)
Executar operações usando A API
Compor solicitações de HTTP e lidar com erros
Consultar dados usando a API da Web
Criar uma entidade 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
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

© 2017 Microsoft. Todos os direitos reservados. Direitos autorais