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 |
|
Usando uma função não associada com parâmetros |
|
Usando uma função associada sem parâmetros |
|
Usando uma ação não associada com parâmetros |
|
Usando uma ação associada com parâmetros |
|
Usando uma ação personalizada associada com parâmetros |
|
Usando uma ação personalizada não associada com parâmetros |
|
Manipulando exceções de ação personalizada |
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.
.jpeg "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.
.jpeg "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