A utilização do parâmetro “$expand” em sua URI da API serve para consultar coleções de dados/objetos dentro das requisições da API utilizada.
Neste artigo, você vai ver:
Utilizando o parâmetro $Expand
De forma simples, o parâmetro “$expand” permite que você aprofunde a sua consulta da API, acessando dados que estejam armazenados em subcoleções ou elementos do diretório de nossa API que está sendo requisitado.
Um exemplo prático desse cenário é a consulta de Campos Adicionais na API de Tickets, para puxar os dados dos campos adicionais existentes nos tickets de sua base de atendimento, através de sua consulta da API.
Nesse caso, primeiro, é importante lembrar da organização da API de Tickets, e de como ela é estruturada.
Verificando no artigo referente à API de Tickets, é possível identificar que cada ticket possui uma coleção de elementos “customFieldValues”, que armazena os dados de campos adicionais e seus valores.
Essa coleção, em casos onde o campo é um campo multivalorado, uma lista, ou semelhante, também possui outra coleção dentro dela, chamada de “items”, onde fica armazenado o valor selecionado neste campo específico.
Portanto, para requisitar os valores de campos adicionais através da API de Tickets, você pode construir a requisição com base no exemplo abaixo:
https://api.movidesk.com/public/v1/tickets?token=[TOKEN DA API]&$select=id&$expand=customFieldValues
Nesse caso, a requisição diz que deve ser selecionado ID dos tickets na API de Tickets, e expandida a coleção de “customFieldValues”. Um exemplo de retorno desta consulta, seria:
{
"id": 12,
"customFieldValues": [
{
"customFieldId": 107064,
"customFieldRuleId": 53163,
"line": 1,
"value": null
}
]
},
Onde aparece, além do ID selecionado (através do $select=id), os dados de um dos campos adicionais do ticket (nesse caso, o campo adicional de id “107064”), dentro da coleção “customFieldValues” no JSON retornado.
Uma questão importante de se ter em mente é que podem existir coleções dentro de coleções, e, para retornar os dados destas “subcoleções” internas, é preciso utilizar o $expand outra vez.
Nesse exemplo da requisição acima, os campos adicionais (customFieldValues) podem ter coleções internas de “items”, dependendo do tipo de campo adicional.
Requisitando dados de coleções dentro de outras coleções
Por conta disso, é sempre interessante também expandir a coleção “items”, dentro da coleção “customFieldValues”. Para isso, é possível aninhar um $expand dentro do outro, ficando com uma requisição semelhante à abaixo:
https://api.movidesk.com/public/v1/tickets?token=[TOKEN DA API]&$select=id&$expand=customFieldValues($expand=items)
Rodando essa requisição (após substituir o valor correto de sua chave da API nela), deve-se então ter os resultados retornados em um formato semelhante ao do JSON a seguir:
{
"id": 11,
"customFieldValues": [
{
"items": [
{
"personId": null,
"clientId": null,
"team": null,
"customFieldItem": "Internamente",
"storageFileGuid": "",
"fileName": null
}
],
"customFieldId": 107064,
"customFieldRuleId": 53163,
"line": 1,
"value": null
}
]
},
Basicamente, essa requisição diz que além de expandir o valor de “customFieldValues”, dentro de cada entidade de “Ticket” retornada, também deveria expandir o valor de “items”, dentro de cada entidade da coleção de “customFieldValues” contida dentro de cada um dos nossos Tickets.
A lógica apresentada aqui para a consulta de Campos Adicionais dentro da API de Tickets pode ser utilizada também para consultar outras coleções nas API’s do Movidesk, como os e-mails de uma pessoa na API de Pessoas (https://api.movidesk.com/public/v1/persons?token=[TOKEN DA API]&$select=id&$expand=emails), as ações de um ticket na API de Tickets (https://api.movidesk.com/public/v1/tickets?token=[TOKEN DA API]&$select=id&$expand=actions), e muitas outras consultas de coleções e entidades nas API’s do Movidesk.
Caso queira maiores detalhes sobre como construir requisições ODATA com o parâmetro $expand, a Microsoft possui uma documentação completa sobre ODATA, com diversos exemplos de URIs e parâmetros, assim como a explicação de cada um deles.
Confira a documentação sobre o $expand, por exemplo:
Para dúvidas ou dificuldades na construção de consultas às nossas API’s, só é necessário entrar em contato com nossos canais de atendimento informando a dificuldade encontrada na utilização dos recursos, a funcionalidade que gostaria de utilizar em nossa API, e a requisição já construída que estaria com algum erro ou dificuldade.