Guia de Requisição
Cabeçalhos e parâmetros são adicionados como campos separados, preenchendo suas respectivas chaves — valor e tipo.
Selecionado na lista, o método é necessário para enviar a solicitação. Métodos disponíveis:
GET
POST
PUT
MERGE
PATCH
DELETE
Registra-se o endereço do endpoint para o qual será enviada a requisição HTTP. Neste campo, é possível escrever tanto texto estático, quanto inserir as variáveis dinâmicas (campos de entidade), por exemplo, passar certos IDs entre barras na URL / /
Além disso, se você usar uma solicitação POST, mas precisar passar alguns parâmetros GET, eles podem ser escritos adicionalmente na própria URL na forma desejada, por exemplo:
A URL deve ser válida e começar com https:// ou http://
Todos os parâmetros GET na URL (após o símbolo "?") passarão pelo procedimento urlencode automaticamente.
Indica-se o formato da solicitação no qual ela será enviada. As seguintes opções estão disponíveis:
JSON
XML
urlEncoded
O cabeçalho apropriado Content-type será colocado automaticamente na solicitação.
No campo de seleção, uma das autorizações criadas no aplicativo tem que ser selecionada. Feito isso, os dados de autorização são inseridos automaticamente na solicitação, não precisando especificá-los adicionalmente a cada nova solicitação. Este é um parâmetro opcional.
Se for necessário enviar cabeçalhos adicionais, campos são adicionados nesta guia. Cada campo à esquerda indica uma chave e, à direita, o valor deste cabeçalho. Por exemplo, quando você precisa enviar um cabeçalho como este:
É preciso clicar no botão "Adicionar campo", preencher o campo à esquerda com o valor "action" e o campo à direita com o valor "create".
No campo direito, é possível usar um parâmetro dinâmico (campos de entidade), que será preenchido no próprio bundle.
É o próprio corpo da requisição. Cada campo que será adicionado aqui formará o corpo da solicitação com o formato e método selecionados. Se o método GET for selecionado, todos os campos criados nesta guia serão automaticamente adicionados à URL como parâmetros GET.
Da mesma forma que na guia do cabeçalho, campos são adicionados, o mapeamento da chave da variável é indicado à esquerda, o valor é escrito no meio e o tipo de variável que será passada é selecionado à direita.
É importante indicar o mapeamento corretamente no campo esquerdo. Vamos pegar o JSON como exemplo. Se você precisar preencher a variável "name", o JSON ficará assim:
Agora, para preencher variável name, você precisa especificar o mapeamento da chave no campo esquerdo como contact.name
Se uma variável está em um conjunto de objetos e é necessário preencher um objeto específico, o mapeamento também é indicado através de um ponto, mas com indicação da posição do objeto no massivo (o cálculo começa do zero). Exemplo o JSON:
Neste caso, se for necessário preencher o name do primeiro objeto, o mapeamento é indicado como contacts.0.name. Se for necessário preencher o segundo objeto, o mapeamento é indicado como contacts.1.name, com o caminho da variável separado por um ponto.
Este cenário é possível quando é necessário preencher uma array de objetos (ou conjunto de objetos), mas o número de objetos no conjunto é previsível. Caso contrário, você precisa criar uma seção de linha nos campos da entidade e criar um campo nos parâmetros selecionando o tipo "Array of objects". Então, serão criados quantos objetos forem necessários, que entrarão na própria seção de linha.
Exemplo de preenchimento:
No campo à direita, na guia de parâmetros, é selecionado o tipo de variável, da forma que deve ser passada na solicitação. As seguintes opções estão disponíveis:
String - Linha String ””
Int - Número inteiro
Decimal - Número fracionário
Boolean - Envia true/false
dateTime - Tipo de data e hora. Este campo é exatamente a data e hora, e deve ser adicionalmente convertido para o formato desejado. Nos campos adicionais, que aparecem na engrenagem, dá para especificar o formato e o fuso horário da data de envio, bem como o formato final da variável (int ou string)
Phone - Outro tipo interno. Quando este tipo é selecionado, os campos com o formato e o tipo final da variável (int ou string) são adicionados à engrenagem. No formato, é selecionada a máscara do número de telefone, para a qual o número será sempre trazido. Este cenário é útil quando o campo com o número de telefone precisa ser enviado à API em um formato estrito (exemplo: +{{countryCode}}##########. Sendo selecionada tal máscara nas configurações, mesmo se o campo contiver um telefone no formato +7(968)111-22-33, a Albato o converterá automaticamente para o formato correto para a API
ObjectArray - O conjunto de objetos. Este tipo é usado junto à seção de linha (que é criada nos campos de entidade). Quando este tipo de solicitação é selecionada, a chave indica o caminho para o próprio conjunto e a seção de linha é definida pelos dados do campo.
Além disso, todos os tipos (exceto ObjectArray) podem ter um tipo adicional com +array no final. Este tipo significa que os dados devem ser transferidos em um massivo de elementos (aproximadamente Array de strings). Ou seja, se você precisar preencher o JSON desta forma:
Em seguida, o tipo StringArray é selecionado. Este tipo é usado se for criada uma ação na qual um campo com o mesmo tipo é preenchido com vários valores separados por vírgulas, que serão automaticamente agrupados em um massivo de linhas.
Além disso, quando esse tipo adicional é selecionado, um campo adicional aparece na engrenagem, no qual você precisa especificar o símbolo separador entre os elementos do massivo (por padrão, o símbolo “,”).
Se for necessário passar a data e a hora na requisição, seleciona-se o tipo de variável necessária. Com essa escolha, o campo na engrenagem terá três campos adicionais:
Tipo - o tipo final da variável, que deve ser passada conforme definida. Pode ser tanto int (neste caso, há uma conversão automática para unixtime), quanto string.
Formato - é necessário preencher o formato da data de acordo com as regras do PHP. A data que cai neste campo (pode ser dd.mm.aaaa hh: mm: ss ou Y-m-d H: i: s) é convertida automaticamente para o formato especificado neste campo. O formato é preenchido de acordo com a documentação do PHP. Ou seja, se o formato for Y/m/d+H:i:s, então a data de recebimento 21.03.2021 19:00:00, será convertida ao formato 2021/03/21+19:00:00 e passada na requisição HTTP.
Fuso horário - o fuso horário da data é selecionado. Qualquer data e hora que caia em tal campo será convertida para o fuso horário selecionado.
Consideramos o tipo de variável ObjectArray separadamente, uma vez que é uma sub-entidade separada da guia da requisição.
Quando este tipo é selecionado, o campo é convertido em um conjunto separado. Essa ação não tem caminho de retorno, só é possível deletar tal campo.
Após a seleção, no campo à esquerda é necessário registrar o mapeamento para o próprio conjunto. No campo direito, a partir do select, selecionar a seção de linha da entidade onde a solicitação está criada. Para este conjunto, é possível adicionar seus próprios campos, que serão cópias dos campos usuais dos parâmetros. Vale destacar que apenas os campos da seção de linha selecionada podem ser usados aqui. Os valores estáticos também são possíveis de vincular.
Para campos criados dentro de um massivo, o mapeamento de chaves deve ser escrito sem especificar o caminho para o massivo. Veja um exemplo para a seguinte estrutura do JSON:
Nesse caso, para o campo criado com o tipo ObjectArray, a chave de mapeamento escreve-se items. Para o conjunto criam-se dois campos e a chave para eles escreve-se name e quantity, com a escolha dos tipos de variáveis necessários. Nesses valores, os campos da entidade são colocados na seção de linha, que será selecionada no campo pai (principal).
Método de requisição
Selecionado na lista, o método é necessário para enviar a solicitação. Métodos disponíveis:
GET
POST
PUT
MERGE
PATCH
DELETE
URL de requisição
Registra-se o endereço do endpoint para o qual será enviada a requisição HTTP. Neste campo, é possível escrever tanto texto estático, quanto inserir as variáveis dinâmicas (campos de entidade), por exemplo, passar certos IDs entre barras na URL / /
Além disso, se você usar uma solicitação POST, mas precisar passar alguns parâmetros GET, eles podem ser escritos adicionalmente na própria URL na forma desejada, por exemplo:
A URL deve ser válida e começar com https:// ou http://
Todos os parâmetros GET na URL (após o símbolo "?") passarão pelo procedimento urlencode automaticamente.
Content-type
Indica-se o formato da solicitação no qual ela será enviada. As seguintes opções estão disponíveis:
JSON
XML
urlEncoded
O cabeçalho apropriado Content-type será colocado automaticamente na solicitação.
Autorização
No campo de seleção, uma das autorizações criadas no aplicativo tem que ser selecionada. Feito isso, os dados de autorização são inseridos automaticamente na solicitação, não precisando especificá-los adicionalmente a cada nova solicitação. Este é um parâmetro opcional.
Cabeçalhos
Se for necessário enviar cabeçalhos adicionais, campos são adicionados nesta guia. Cada campo à esquerda indica uma chave e, à direita, o valor deste cabeçalho. Por exemplo, quando você precisa enviar um cabeçalho como este:
curl -H "Action: create"É preciso clicar no botão "Adicionar campo", preencher o campo à esquerda com o valor "action" e o campo à direita com o valor "create".
No campo direito, é possível usar um parâmetro dinâmico (campos de entidade), que será preenchido no próprio bundle.
Parâmetros
É o próprio corpo da requisição. Cada campo que será adicionado aqui formará o corpo da solicitação com o formato e método selecionados. Se o método GET for selecionado, todos os campos criados nesta guia serão automaticamente adicionados à URL como parâmetros GET.
Da mesma forma que na guia do cabeçalho, campos são adicionados, o mapeamento da chave da variável é indicado à esquerda, o valor é escrito no meio e o tipo de variável que será passada é selecionado à direita.
É importante indicar o mapeamento corretamente no campo esquerdo. Vamos pegar o JSON como exemplo. Se você precisar preencher a variável "name", o JSON ficará assim:
{"name":"Fulano"}A chave é especificada como name .Se a variável necessária estiver dentro de um conjunto do objeto e você precisar preenchê-la, o caminho para o objeto será indicado por meio de um ponto, separando o caminho da variável. Exemplo o JSON:{"contact":{ "name":"Albato" }}Agora, para preencher variável name, você precisa especificar o mapeamento da chave no campo esquerdo como contact.name
Se uma variável está em um conjunto de objetos e é necessário preencher um objeto específico, o mapeamento também é indicado através de um ponto, mas com indicação da posição do objeto no massivo (o cálculo começa do zero). Exemplo o JSON:
{"contacts":[ { "name":"Albato" }, { "name":"Albato 2" }]}Neste caso, se for necessário preencher o name do primeiro objeto, o mapeamento é indicado como contacts.0.name. Se for necessário preencher o segundo objeto, o mapeamento é indicado como contacts.1.name, com o caminho da variável separado por um ponto.
Este cenário é possível quando é necessário preencher uma array de objetos (ou conjunto de objetos), mas o número de objetos no conjunto é previsível. Caso contrário, você precisa criar uma seção de linha nos campos da entidade e criar um campo nos parâmetros selecionando o tipo "Array of objects". Então, serão criados quantos objetos forem necessários, que entrarão na própria seção de linha.
Exemplo de preenchimento:
Tipos de variáveis
No campo à direita, na guia de parâmetros, é selecionado o tipo de variável, da forma que deve ser passada na solicitação. As seguintes opções estão disponíveis:
String - Linha String ””
Int - Número inteiro
Decimal - Número fracionário
Boolean - Envia true/false
dateTime - Tipo de data e hora. Este campo é exatamente a data e hora, e deve ser adicionalmente convertido para o formato desejado. Nos campos adicionais, que aparecem na engrenagem, dá para especificar o formato e o fuso horário da data de envio, bem como o formato final da variável (int ou string)
Phone - Outro tipo interno. Quando este tipo é selecionado, os campos com o formato e o tipo final da variável (int ou string) são adicionados à engrenagem. No formato, é selecionada a máscara do número de telefone, para a qual o número será sempre trazido. Este cenário é útil quando o campo com o número de telefone precisa ser enviado à API em um formato estrito (exemplo: +{{countryCode}}##########. Sendo selecionada tal máscara nas configurações, mesmo se o campo contiver um telefone no formato +7(968)111-22-33, a Albato o converterá automaticamente para o formato correto para a API
ObjectArray - O conjunto de objetos. Este tipo é usado junto à seção de linha (que é criada nos campos de entidade). Quando este tipo de solicitação é selecionada, a chave indica o caminho para o próprio conjunto e a seção de linha é definida pelos dados do campo.
Além disso, todos os tipos (exceto ObjectArray) podem ter um tipo adicional com +array no final. Este tipo significa que os dados devem ser transferidos em um massivo de elementos (aproximadamente Array de strings). Ou seja, se você precisar preencher o JSON desta forma:
{"tags":[ "tag", "tag2", "tag3"]}Em seguida, o tipo StringArray é selecionado. Este tipo é usado se for criada uma ação na qual um campo com o mesmo tipo é preenchido com vários valores separados por vírgulas, que serão automaticamente agrupados em um massivo de linhas.
Além disso, quando esse tipo adicional é selecionado, um campo adicional aparece na engrenagem, no qual você precisa especificar o símbolo separador entre os elementos do massivo (por padrão, o símbolo “,”).
Data e hora
Se for necessário passar a data e a hora na requisição, seleciona-se o tipo de variável necessária. Com essa escolha, o campo na engrenagem terá três campos adicionais:
Tipo - o tipo final da variável, que deve ser passada conforme definida. Pode ser tanto int (neste caso, há uma conversão automática para unixtime), quanto string.
Formato - é necessário preencher o formato da data de acordo com as regras do PHP. A data que cai neste campo (pode ser dd.mm.aaaa hh: mm: ss ou Y-m-d H: i: s) é convertida automaticamente para o formato especificado neste campo. O formato é preenchido de acordo com a documentação do PHP. Ou seja, se o formato for Y/m/d+H:i:s, então a data de recebimento 21.03.2021 19:00:00, será convertida ao formato 2021/03/21+19:00:00 e passada na requisição HTTP.
Fuso horário - o fuso horário da data é selecionado. Qualquer data e hora que caia em tal campo será convertida para o fuso horário selecionado.
Conjunto de objetos
Consideramos o tipo de variável ObjectArray separadamente, uma vez que é uma sub-entidade separada da guia da requisição.
Quando este tipo é selecionado, o campo é convertido em um conjunto separado. Essa ação não tem caminho de retorno, só é possível deletar tal campo.
Após a seleção, no campo à esquerda é necessário registrar o mapeamento para o próprio conjunto. No campo direito, a partir do select, selecionar a seção de linha da entidade onde a solicitação está criada. Para este conjunto, é possível adicionar seus próprios campos, que serão cópias dos campos usuais dos parâmetros. Vale destacar que apenas os campos da seção de linha selecionada podem ser usados aqui. Os valores estáticos também são possíveis de vincular.
Para campos criados dentro de um massivo, o mapeamento de chaves deve ser escrito sem especificar o caminho para o massivo. Veja um exemplo para a seguinte estrutura do JSON:
{"items":[ { "name":"Albato1", "quantity":1 }, { "name":"Albato2", "quantity":3 }]}Nesse caso, para o campo criado com o tipo ObjectArray, a chave de mapeamento escreve-se items. Para o conjunto criam-se dois campos e a chave para eles escreve-se name e quantity, com a escolha dos tipos de variáveis necessários. Nesses valores, os campos da entidade são colocados na seção de linha, que será selecionada no campo pai (principal).
Atualizado em: 01/12/2022
Obrigado!