Partilhar via


Exemplo de funções API da Web e ações

 

Publicado: janeiro de 2017

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

Este grupo de exemplos demonstra como executar funções e ações associadas e não associadas, incluindo ações personalizadas, usando a API Web do Microsoft Dynamics 365. Este exemplo foi implementado como um projeto separado para as seguintes linguagens:

Este tópico explica a estrutura e o conteúdo do exemplo em um nível mais alto e com neutralidade de idioma. Revise os tópicos vinculados de exemplo acima para obter detalhes de implementação específicos do idioma e detalhes relacionados sobre como realizar as operações descritas neste tópico.

Demonstrações

Este exemplo é dividido nas seções principais a seguir, contendo operações de funções e de ações da API da Web que são abordadas detalhadamente nos tópicos conceituais associados.

Seção do tópico

Tópico(s) associado(s)

Dados de exemplo

Usando uma função não associada sem parâmetros

Funções dissociadas

WhoAmI Function

systemuser EntityType

Usando uma função não associada com parâmetros

Funções dissociadas

GetTimeZoneCodeByLocalizedName Function

Usando uma função associada sem parâmetros

Funções associadas

CalculateTotalTimeIncident Function

Usando uma ação não associada com parâmetros

Ações desvinculadas

WinOpportunity Action

opportunity EntityType

Usando uma ação associada com parâmetros

Ações vinculadas

AddToQueue Action

WhoAmI Function

systemuser EntityType

letter EntityType

Usando uma ação personalizada associada com parâmetros

Usar uma ação personalizada

Ações vinculadas

contact EntityType

Usando uma ação personalizada não associada com parâmetros

Usar uma ação personalizada

Ações desvinculadas

account EntityType

Manipulando exceções de ação personalizada

Usar uma ação personalizada

Ações desvinculadas

contact EntityType

As seções a seguir contêm uma breve discussão das operações executadas da API da Web do Dynamics 365, juntamente com as mensagens HTTP correspondentes e saídas de console associadas.

Dados de exemplo

Para garantir que as operações deste exemplo funcionem adequadamente, primeiro criamos os dados de exemplo no servidor do Dynamics 365. Esses dados de exemplo serão excluídos do servidor, a menos que o usuário opte por não excluí-los. Os dados deste exemplo são criados individualmente, como a seguir.

  • Crie uma conta (por exemplo: Fourth Coffee) e a associe a um incidente com três tarefas de 30 minutos (total de 90 minutos). Após a criação das tarefas, elas serão marcadas como concluídas. A operação calculará o tempo total necessário para a conclusão dessas três tarefas.

    {
      title: "Sample Case",
      "customerid_account@odata.bind": accountUri,
      Incident_Tasks: [
       {
        subject: "Task 1",
        actualdurationminutes: 30
       },
       {
        subject: "Task 2",
        actualdurationminutes: 30
       },
       {
        subject: "Task 3",
        actualdurationminutes: 30
       }
      ]
     };
    
  • Crie uma conta e a associe a uma oportunidade. Essa oportunidade será marcada como ganha na operação de exemplo.

    {
     name: "Sample Account for WebAPIFunctionsAndActions sample",
     opportunity_customer_accounts: [{
      name: "Opportunity to win"
     }]
    };
    
  • Crie uma atividade de carta. A carta será adicionada à fila do usuário atual na operação de exemplo.

    {
      description: "Example letter"
    }
    
  • Crie um contato para ser usado como uma ação personalizada sample_AddNoteToContact na operação de exemplo.

    {
      firstname: "Jon",
      lastname: "Fogg"
    }
    

Operações de exemplo

As operações de exemplo deste tópico estão organizadas das seguintes maneiras.

  • Trabalhando com funções: essas operações mostram funções associadas e não associadas que aceitam parâmetros ou não.

  • Trabalhando com ações: essas operações mostram ações associadas e não associadas que aceitam parâmetros ou não.

  • Ações personalizadas: essas operações mostram ações associadas e não associadas e como lidar com exceções de erro personalizadas.

Trabalhando com funções

Functions são operações que não têm efeitos colaterais. Uma função pode ser associada a uma instância de entidade ou a uma coleção de entidades. As funções de consulta nunca são associadas. Para obter mais informações, consulte Usar funções da API Web. Esta seção mostra exemplos de como as funções associadas e não associadas são usadas e como os parâmetros são passados.

Usando uma função não associada sem parâmetros

Use uma função não associada para recuperar o nome completo do usuário atual ao fazer uso da WhoAmI Function. Esta operação demonstra como chamar uma função não associada que não aceita parâmetros. Essa operação retorna o nome completo do usuário atual.

Obtendo a solicitação e a resposta da WhoAmI Function.

Solicitação HTTP

GET http://cc_WebAPI_ServiceURI/WhoAmI HTTP/1.1
OData-MaxVersion: 4.0
OData-Version: 4.0
Content-Type: application/json; charset=utf-8

Resposta HTTP

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

{
   "@odata.context":"http://cc_WebAPI_ServiceURI/$metadata#Microsoft.Dynamics.CRM.WhoAmIResponse",
   "BusinessUnitId":"0d6cc84a-d3f6-e511-80d0-00155da84802",
   "UserId":"b08dc84a-d3f6-e511-80d0-00155da84802",
   "OrganizationId":"0f47eae2-a906-4ae4-9215-f09875979f6a"
}

Usando uma função não associada com parâmetros

Use uma função não associada para recuperar o código de fuso horário. Esta operação demonstra como chamar uma função não associada que aceita parâmetros. Esta operação retorna o fuso horário atual para o fuso horário especificado.Para obter mais informações:Transmitindo parâmetros para uma função

Solicitação HTTP

GET http://cc_WebAPI_ServiceURI/GetTimeZoneCodeByLocalizedName(LocalizedStandardName=@p1,LocaleId=@p2)?@p1='Pacific%20Standard%20Time'&@p2=1033 HTTP/1.1
OData-MaxVersion: 4.0
OData-Version: 4.0
Content-Type: application/json; charset=utf-8

Resposta HTTP

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

{
   "@odata.context":"http://cc_WebAPI_ServiceURI/$metadata#Microsoft.Dynamics.CRM.GetTimeZoneCodeByLocalizedNameResponse",
   "TimeZoneCode":4
}

Saída do console

Unbound function: GetTimeZoneCodeByLocalizedName
    Function returned time zone Pacific Standard Time, with code '4'.

Usando uma função associada sem parâmetros

Use uma função associada para recuperar o tempo total para a conclusão de todas as tarefas de um incidente. Esta operação demonstra como chamar uma função associada que não aceita parâmetros. Esta operação retorna o total de minutos que o incidente levou para fechar todas as suas tarefas. Essa função também usa os dados do incidente que criamos para este programa de exemplo.Para obter mais informações:Funções associadas

Solicitação HTTP

GET http://cc_WebAPI_ServiceURI/incidents(3d920da5-fb4a-e611-80d5-00155da84802)/Microsoft.Dynamics.CRM.CalculateTotalTimeIncident() HTTP/1.1
OData-MaxVersion: 4.0
OData-Version: 4.0
Content-Type: application/json; charset=utf-8

Resposta HTTP

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

{
   "@odata.context":"http://cc_WebAPI_ServiceURI/$metadata#Microsoft.Dynamics.CRM.CalculateTotalTimeIncidentResponse",
   "TotalTime":90
}

Saída do console

Bound function: CalculateTotalTimeIncident
    Function returned 90 minutes - total duration of tasks associated with the incident.

Trabalhando com ações

Ações são operações com efeitos colaterais. Uma ação ou associada ou não associada. Para obter mais informações, consulte Use ações API da Web. Esta seção mostra exemplos de como as ações associadas e não associadas são usadas e como os parâmetros são passados. Ela também mostra como as ações personalizadas são usadas e como lidar com exceções dessas ações personalizadas.

Usando uma ação não associada com parâmetros

Use uma ação não associada que aceite um conjunto de parâmetros. Esta operação fecha uma oportunidade e a marca como ganha ao chamar a WinOpportunity Action. O opportunity EntityType foi criado como dados de exemplo anteriormente no programa.Para obter mais informações:Ações desvinculadas

Solicitação HTTP

POST http://cc_WebAPI_ServiceURI/WinOpportunity HTTP/1.1
OData-MaxVersion: 4.0
OData-Version: 4.0
Content-Type: application/json; charset=utf-8

{
   "Status":3,
   "OpportunityClose":{
      "subject":"Won Opportunity",
      "opportunityid@odata.bind":"http://cc_WebAPI_ServiceURI/opportunities(47920da5-fb4a-e611-80d5-00155da84802)"
   }
}

Resposta HTTP

HTTP/1.1 204 No Content
OData-Version: 4.0

Saída do console

Unbound Action: WinOpportunity
    Opportunity won.

Usando uma ação associada com parâmetros

Use uma ação associada que aceite parâmetros. Esta operação adiciona uma carta à fila do usuário atual. Para fazer isso, usamos a WhoAmI Function e o systemuser EntityType para obtermos uma referência à fila do usuário atual. Também é necessário fazer referência ao letter EntityType. Esta carta foi criada como dados de exemplo anteriormente no programa. Então, a AddToQueue Action associada é chamada para adicionar a carta à fila do usuário atual.Para obter mais informações:Ações vinculadas

Solicitação HTTP

POST http://cc_WebAPI_ServiceURI/queues(1f7bcc50-d3f6-e511-80d0-00155da84802)/Microsoft.Dynamics.CRM.AddToQueue HTTP/1.1
OData-MaxVersion: 4.0
OData-Version: 4.0
Content-Type: application/json; charset=utf-8
Content-Length: 110

{
   "Target":{
      "activityid":"4c920da5-fb4a-e611-80d5-00155da84802",
      "@odata.type":"Microsoft.Dynamics.CRM.letter"
   }
}

Resposta HTTP

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

{
   "@odata.context":"http://cc_WebAPI_ServiceURI/$metadata#Microsoft.Dynamics.CRM.AddToQueueResponse",
   "QueueItemId":"67bdfabd-fc4a-e611-80d5-00155da84802"
}

Saída do console

Bound Action: AddToQueue
    QueueItemId returned from AddToQueue Action: 67bdfabd-fc4a-e611-80d5-00155da84802

Trabalhando com ações personalizadas

Se você definir ações personalizadas para sua solução, poderá chamá-las usando a API Web do Dynamics 365. 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.Para obter mais informações:Usar uma ação personalizada.

Este exemplo vem com duas ações personalizadas. Ambas exigem parâmetros, mas uma é associada e a outra é não associada.

  • sample_AddNoteToContact: uma ação personalizada associada que aceita dois parâmetros. Um é NoteTitle e o outro é NoteText. Essa ação personalizada adiciona uma notação a um contact EntityType. Abaixo, uma captura de tela da página Informações para esta ação personalizada.

    Custom Action - AddNoteToContact information

  • sample_CreateCustomer: uma ação personalizada não associada que exige parâmetros diferentes, dependendo do tipo de cliente que está sendo criado. Por exemplo, quando o AccountType for "conta", então ele só exigirá o parâmetro AccountName. Quando o AccountType for "contato, os parâmetros ContactFirstName e ContactLastName serão necessários. Abaixo, uma captura de tela da página Informações para esta ação personalizada.

    Custom Action - CreateCustomer information

Usando uma ação personalizada associada com parâmetros

Este exemplo chama a ação personalizada sample_AddNoteToContact, que está associada à entidade de contato com os parâmetros necessários. Esta ação personalizada adiciona uma anotação a um contato existente. Esta ação retorna uma entidade com uma propriedade annotationid. Para mostrar que a anotação foi adicionada, a annotationid é usada para solicitar informações sobre a anotação.

A solicitação e a resposta da ação.

Solicitação HTTP

POST http://cc_WebAPI_ServiceURI/contacts(4d920da5-fb4a-e611-80d5-00155da84802)/Microsoft.Dynamics.CRM.sample_AddNoteToContact HTTP/1.1
OData-MaxVersion: 4.0
OData-Version: 4.0
Content-Type: application/json; charset=utf-8
Content-Length: 80

{
   "NoteTitle":"The Title of the Note",
   "NoteText":"The text content of the note."
}

Resposta HTTP

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

{
   "@odata.context":"http://cc_WebAPI_ServiceURI/$metadata#annotations/$entity",
   "annotationid":"ba146d0b-fd4a-e611-80d5-00155da84802"
}

A solicitação e a resposta da anotação.

Solicitação HTTP

GET http://cc_WebAPI_ServiceURI/annotations(ba146d0b-fd4a-e611-80d5-00155da84802)?$select=subject,notetext&$expand=objectid_contact($select=fullname) HTTP/1.1
OData-MaxVersion: 4.0
OData-Version: 4.0
Content-Type: application/json; charset=utf-8

Resposta HTTP

HTTP/1.1 200 OK
OData-Version: 4.0
Content-Length: 450

{
   "@odata.context":"http://cc_WebAPI_ServiceURI/$metadata#annotations(subject,notetext,objectid_contact,objectid_contact(fullname))/$entity",
   "@odata.etag":"W/\"622978\"",
   "subject":"The Title of the Note",
   "notetext":"The text content of the note.",
   "annotationid":"ba146d0b-fd4a-e611-80d5-00155da84802",
   "objectid_contact":{
      "@odata.etag":"W/\"622968\"",
      "fullname":"Jon Fogg",
      "contactid":"4d920da5-fb4a-e611-80d5-00155da84802"
   }
}

Saída do console

Custom action: sample_AddNoteToContact
    A note with the title 'The Title of the Note' and the content 'The text content of the note.' was created and associated with the contact Jon Fogg.

Usando uma ação personalizada não associada com parâmetros

Esta operação chama a ação personalizada sample_CreateCustomer para criar um cliente "conta". Os parâmetros necessários são passados para um CustomerType de account.

Solicitação HTTP

POST http://cc_WebAPI_ServiceURI/sample_CreateCustomer HTTP/1.1
OData-MaxVersion: 4.0
OData-Version: 4.0
Content-Type: application/json; charset=utf-8
Content-Length: 103

{
   "CustomerType":"account",
   "AccountName":"Account Customer Created in WebAPIFunctionsAndActions sample"
}

Resposta HTTP

HTTP/1.1 204 No Content
OData-Version: 4.0

Manipulando exceções de ação personalizada

Este exemplo mostra que as ações personalizadas podem retornar mensagens de erro personalizadas. Você manipula as exceções personalizadas da mesma forma como manipula as exceções padrão. Para obter a mensagem de erro personalizada da ação personalizada sample_CreateCustomer , este exemplo cria um cliente "contato". Entretanto, nós passarmos intencionalmente parâmetros incorretos para este parâmetro CustomerType. Esta operação então captura a exceção e exibe a mensagem de erro e continua com o programa de exemplo.

Solicitação HTTP

POST http://cc_WebAPI_ServiceURI/sample_CreateCustomer HTTP/1.1
OData-MaxVersion: 4.0
OData-Version: 4.0
Content-Type: application/json; charset=utf-8
Content-Length: 103

{
   "CustomerType":"contact",
   "AccountName":"Account Customer Created in WebAPIFunctionsAndActions sample"
}

Resposta HTTP

HTTP/1.1 500 Internal Server Error
Content-Type: application/json; odata.metadata=minimal
OData-Version: 4.0
Content-Length: 2760

{
   "error":{
      "code":"",
      "message":"ContactFirstName and ContactLastName are required when CustomerType is contact.",
      "innererror":{
         "message":"ContactFirstName and ContactLastName are required when CustomerType is contact.",
         ...[truncated]
      }
   }
}

Saída do console

Expected custom error: ContactFirstName and ContactLastName are required when CustomerType is contact.

Confira Também

Use a API da Web do Microsoft Dynamics 365
Usar funções da API Web
Use ações API da Web
Exemplo de funções API da Web e ações (C#)
Funções da API Web e Amostra de ações (Javascript do cliente)

Microsoft Dynamics 365

© 2017 Microsoft. Todos os direitos reservados. Direitos autorais