Usar funções da API Web
Publicado: janeiro de 2017
Aplicável a: Dynamics 365 (online), Dynamics 365 (on-premises), Dynamics CRM 2016, Dynamics CRM Online
Funções e ações representam operações reutilizáveis que você pode realizar usando a API Web. Há dois tipos de funções na API Web:
Functions
Use uma solicitação GET com funções listadas em Web API Function Reference para realizar operações que não apresentam efeitos colaterais. Geralmente, essas funções recuperam dados. Elas retornam uma coleção ou um tipo complexo. Cada uma dessas funções tem uma mensagem correspondente no serviço da organização.Funções de consulta
Use as funções listadas em Web API Query Function Reference para avaliar propriedades e valores na composição de uma consulta. Cada um dessas funções tem um valor ConditionOperator correspondente.
Neste tópico
Transmitindo parâmetros para uma função
Passar referência a uma entidade para uma função
Funções associadas e dissociadas
Redija uma consulta com funções
Transmitindo parâmetros para uma função
Para as funções que requerem parâmetros, a prática recomendada é transmitir os valores por meio de parâmetros. Por exemplo, ao usar GetTimeZoneCodeByLocalizedName Function, você deve incluir os valores de parâmetro LocalizedStandardName e LocaleId. Portanto, você pode usar a seguinte sintaxe embutida mostrada aqui.
GET cc_WebAPI_ServiceURI/GetTimeZoneCodeByLocalizedName(LocalizedStandardName='Pacific Standard Time',LocaleId=1033)
Entretanto, há um problema em aberto quanto ao uso dos valores DateTimeOffset com a sintaxe embutida, conforme explicado neste artigo: DateTimeOffset como parâmetro de consulta 204.
Portanto, a prática recomendada é transmitir os valores como parâmetros, conforme mostrado no código de exemplo. Se você usar essa prática recomendada, poderá evitar o problema em aberto aplicável a DateTimeOffset.
GET cc_WebAPI_ServiceURI/GetTimeZoneCodeByLocalizedName(LocalizedStandardName=@p1,LocaleId=@p2)?@p1='Pacific Standard Time'&@p2=1033
Os alias de parâmetro também permitem que você reutilize valores de parâmetro para reduzir o tamanho total da URL quando o valor de parâmetro for usado várias vezes.
Passar referência a uma entidade para uma função
Determinadas funções exigirão a passagem de uma referência a uma entidade existente. Por exemplo, as seguintes funções têm um parâmetro que exige um crmbaseentity EntityType:
Quando você passar uma referência a uma entidade existente, use a anotação @odata.id para o Uri da entidade. Por exemplo, se você estiver usando a RetrievePrincipalAccess Function, poderá usar o Uri a seguir para especificar o acesso de recuperação para um contato específico:
GET cc_WebAPI_ServiceURI/systemusers(af9b3cf6-f654-4cd9-97a6-cf9526662797)/Microsoft.Dynamics.CRM.RetrievePrincipalAccess(Target=@tid)?@tid={'@odata.id':'contacts(9f3162f6-804a-e611-80d1-00155d4333fa)'}
A anotação @odata.id pode ser o Uri completo, mas um Uri relativo também funcionará.
Funções associadas e dissociadas
Somente as funções encontradas em Web API Function Reference podem ser associadas. As funções de consulta nunca são associadas.
Funções associadas
No d80cfb87-d4f1-4c75-bcc8-4f54d1351e26#bkmk_csdl, quando um elemento Function representa uma ação associada, ele tem um atributo IsBound com o valor true. O primeiro elemento Parameter definido na função representa a entidade à qual a função está associada. Quando o atributo Type do parâmetro é uma coleção, a função está associada a uma coleção de entidades. Como exemplo, esta é a definição de CalculateTotalTimeIncident Function e CalculateTotalTimeIncidentResponse ComplexType no CSDL:
<ComplexType Name="CalculateTotalTimeIncidentResponse">
<Property Name="TotalTime" Type="Edm.Int64" Nullable="false" />
</ComplexType>
<Function Name="CalculateTotalTimeIncident" IsBound="true">
<Parameter Name="entity" Type="mscrm.incident" Nullable="false" />
<ReturnType Type="mscrm.CalculateTotalTimeIncidentResponse" Nullable="false" />
</Function>
Essa função associada é equivalente ao CalculateTotalTimeIncidentRequest usado pelo serviço da organização. Na API Web, essa função está associada ao incident EntityType, que representa a propriedade CalculateTotalTimeIncidentRequest.IncidentId. Em vez de retornar CalculateTotalTimeIncidentResponse, essa função retorna CalculateTotalTimeIncidentResponse ComplexType. Quando uma função retorna um tipo complexo, sua definição aparece diretamente acima da definição da função no CSDL.
Para ativar uma função associada, acrescente o nome completo da função a URL e coloque qualquer parâmetro nomeado entre parênteses após o nome da função. O nome completo da função inclui o namespace Microsoft.Dynamics.CRM. As funções que não são associadas não devem usar o nome completo.
Importante
Uma função associada deve ser chamada por meio de um URI para definir o primeiro valor de parâmetro. Não é possível defini-la como um valor de parâmetro nomeado.
O exemplo a seguir mostra a CalculateTotalTimeIncident Function, que está associada à entidade do incidente.
Solicitação
GET cc_WebAPI_ServiceURI/incidents(90427858-7a77-e511-80d4-00155d2a68d1)/Microsoft.Dynamics.CRM.CalculateTotalTimeIncident() HTTP/1.1 Accept: application/json OData-MaxVersion: 4.0 OData-Version: 4.0Resposta
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.CalculateTotalTimeIncidentResponse","TotalTime":30 }
Funções dissociadas
WhoAmI Function não está associada a uma entidade. Ela é definida no CSDL sem um atributo IsBound.
<ComplexType Name="WhoAmIResponse">
<Property Name="BusinessUnitId" Type="Edm.Guid" Nullable="false" />
<Property Name="UserId" Type="Edm.Guid" Nullable="false" />
<Property Name="OrganizationId" Type="Edm.Guid" Nullable="false" />
</ComplexType>
<Function Name="WhoAmI">
<ReturnType Type="mscrm.WhoAmIResponse" Nullable="false" />
</Function>
Essa função corresponde a WhoAmIRequest e retorna WhoAmIResponse ComplexType, que corresponde à WhoAmIResponse usada pelo serviço da organização. Essa função não tem nenhum parâmetro.
Ao chamar uma função dissociada, utilize apenas o nome da função, conforme mostrado no exemplo a seguir.
Solicitação
GET cc_WebAPI_ServiceURI/WhoAmI() HTTP/1.1 Accept: application/json OData-MaxVersion: 4.0 OData-Version: 4.0Resposta
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.WhoAmIResponse", "BusinessUnitId": "ded5a64f-f06d-e511-80d0-00155db07cb1", "UserId": "d96e9f55-f06d-e511-80d0-00155db07cb1", "OrganizationId": "4faf1f34-f06d-e511-80d0-00155db07cb1" }
Redija uma consulta com funções
As funções podem ser usadas de duas maneiras para controlar os dados retornados com as consultas. Determinadas funções permitem o controle sobre as colunas ou as condições que elas retornam; use as funções de consulta para avaliar as condições de uma consulta.
Funções combináveis
Algumas funções listadas em Web API Function Reference retornarão uma coleção de entidades. Um subconjunto dessas funções será composable, o que significa que você pode incluir uma opção de consulta de sistema adicional $select ou $filter para controlar quais colunas serão retornadas nos resultados. Essas funções têm um atributo IsComposable no CSDL. Cada uma dessas funções tem uma mensagem complementar no serviço da organização que aceita um parâmetro do tipo ColumnSet ou QueryBase. As opções de consulta de sistema OData fornecem a mesma funcionalidade para que essas funções não apresentem os mesmos parâmetros das mensagens complementares no serviço da organização. A tabela a seguir mostra uma lista das funções composable nesta versão.
Funções de consulta
As funções listadas em Web API Query Function Reference foram projetadas para redigir uma consulta. Essas funções podem ser usadas da mesma forma que Funções de consulta padrão, mas há algumas diferenças importantes.
Use o nome completo da função e incluir os nomes dos parâmetros. O exemplo a seguir mostra como usar LastXHours Function para retornar todas as entidades de conta modificadas nas últimas 12 horas.
GET cc_WebAPI_ServiceURI/accounts?$select=name,accountnumber&$filter=Microsoft.Dynamics.CRM.LastXHours(PropertyName=@p1,PropertyValue=@p2)&@p1='modifiedon'&@p2=12
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
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
© 2017 Microsoft. Todos os direitos reservados. Direitos autorais