Use uma API REST em Operações¶

Introdução¶

Embora cada API REST siga as mesmas restrições de arquitetura, nem todas são projetadas da mesma maneira para cada método HTTP. Por exemplo, para um POST, uma API pode receber uma estrutura de solicitação e fornecer uma estrutura de resposta, enquanto outra API pode receber uma estrutura de solicitação, mas responder apenas com um código de status. Para um DELETE, uma API pode exigir que a solicitação seja fornecida na URL em vez de uma estrutura.

Como cada método pode ser diferente, é importante verificar a documentação da API específica (Researching a REST API) e ter validado a requisição e a resposta com uma ferramenta independente (Validating a REST API). Portanto, em vez de fornecer padrões para cada método, que podem variar de acordo com a API, os padrões apresentados a seguir são baseados no fornecimento de estruturas de solicitação ou resposta.

Nesta página, veremos esses padrões de design e veremos como modelá-los no Design Studio:

Somente uma estrutura de resposta
Estruturas de solicitação e resposta
Somente uma estrutura de solicitação
Nem uma solicitação nem uma estrutura de resposta

Os padrões continuam o Tutorial da API REST usando Atlassian Jira Cloud REST API v2 como um exemplo. No entanto, não é necessário concluir as etapas anteriores do tutorial para usar esses padrões, que são aplicáveis em APIs REST em geral.

Apenas uma Estrutura de Resposta¶

Esse padrão se aplica a métodos nos quais você precisa fornecer apenas uma estrutura de resposta e nenhuma estrutura de solicitação. Geralmente, esse é o caso dos métodos GET, já que normalmente você está apenas solicitando que os dados sejam enviados de volta da API, em vez de fornecer dados para a API. Você ainda está enviando uma solicitação para a API, mas sua solicitação não está na forma de dados estruturados. A solicitação é feita simplesmente usando a URL da solicitação e quaisquer cabeçalhos de solicitação ou outras opções configuráveis definidas durante a configuração da fonte HTTP.

Neste exemplo do padrão, fazemos uma solicitação usando um método GET ("GET Jira Issue"), passamos os dados recebidos pela transformação ("Issue") e gravamos os dados retornados da API em uma variável global target ("Resposta"), que gravamos no log da operação usando um script ("Log de depuração") para relatar os dados retornados.

Uma estrutura de resposta apenas 1

Observe que qualquer outro destino pode ser usado e que o método e o que ele retorna dependem da API específica. Esse padrão pode ser modificado dependendo de como você gostaria de usar os dados de resposta retornados da API.

Crie uma operação de transformação usando uma origem HTTP com o HTTP Verb e URL para a solicitação de API específica.
Na operação, clique duas vezes no marcador de posição de destino e crie uma variável global de destino com uma variável chamada "Resposta". (Qualquer tipo de alvo pode ser usado aqui.)
Na operação, clique com o botão direito do mouse no destino da variável global que você acabou de adicionar e selecione Inserir depois disso > Script. Em seguida, clique duas vezes no script e crie um novo Jitterbit Script onde escreveremos o valor da variável global no log da operação:
```
<trans>
WriteToOperationLog($Response)
</trans>
```
Na operação, clique duas vezes no espaço reservado da transformação e crie uma nova transformação. Aqui é onde forneceremos a estrutura de resposta de amostra para que o Harmony saiba como processar os dados.
1. Na etapa Nome do assistente de transformação, selecione o formato da origem e destino dos dados. No exemplo, selecionamos "JSON" para ambos, pois a API do Jira fornece respostas neste formato.
2. Na etapa Source, selecione a opção para criar uma nova estrutura a partir de um arquivo de amostra. Na próxima tela, forneça o arquivo de resposta de amostra que você salvou da validação da API para esse tipo de solicitação e gere o XSD desse arquivo de amostra. Em nosso exemplo, geramos o XSD a partir do Jira_GET_GetIssue_Response.json exemplo de resposta que salvamos anteriormente (consulte Validando uma API REST).
3. Na etapa Target, selecione o mesmo esquema que você acabou de gerar, pois neste caso a origem e a estrutura de destino serão idênticas.
Na tela de mapeamento da transformação, mapeie automaticamente os campos de origem e destino, que devem ser uma correspondência exata, pois estão usando a mesma estrutura. Isso passará por todos os campos retornados da API.

Se você deseja transformar qualquer um dos dados, pode fazê-lo agora. No entanto, é comum apenas passar os dados obtidos de um GET para que você possa ver o que a API está retornando e, possivelmente, usar esses dados em uma operação posterior. Você também pode mapear diretamente para outros endpoints configurados.
Quando estiver pronto, implantar e execute a operação. Clique duas vezes no(s) ícone(s) de status no monitor de operação para visualizar informações sobre o status da operação. Se a operação for concluída com êxito, você verá esse status, bem como a resposta da API que configurou para gravar no log da operação.

Como removemos campos de nossa estrutura de exemplo antes de gerar o XSD para a transformação, o status mostra conclusão bem-sucedida com avisos. Os avisos são incluídos mais abaixo na mensagem de log.

Você também pode clicar com o botão direito do mouse na operação e selecionar Operation Log para ver os avisos diretamente no log da operação:

Estruturas de Solicitação e Resposta¶

Esse padrão se aplica a métodos nos quais você fornece estruturas de solicitação e resposta. Geralmente, esse é o caso dos métodos POST, nos quais você solicita que os dados sejam criados e, em seguida, recebe informações sobre o que foi criado. A resposta da API pode ser usada de qualquer maneira, mas geralmente é o caso de usar os novos IDs de objeto em uma operação posterior.

Muitas APIs REST têm métodos POST ou PUT que permitem criar apenas um registro por vez. Nessa situação, se você tiver uma origem com vários registros, chame um método para criar ou atualizar um registro por vez. Por esse motivo, esse padrão não usa uma fonte de item de projeto como normalmente visto em operações do Harmony. Em vez disso, usamos um script para percorrer vários registros, alimentando-os na mesma operação para serem processados um por vez.

Neste exemplo do padrão, percorremos vários registros de origem para fazer uma solicitação para cada um usando um método POST e gravamos os dados retornados da API em uma variável global de destino, que gravamos no log da operação para analisar a resposta e relatar os dados retornados. Para fazer isso, encadeamos três operações, abordadas em detalhes nas seguintes subseções:

Crie um loop de registros. Na primeira operação, "1.0 Loop to Submit", usamos um script ("Create Sample Data") para criar uma variável global que usamos como fonte ("CSV Source") para a transformação ("Loop"), onde escrevemos valores de campo para cada registro de origem em variáveis globais.
Enviar a Solicitação. Na segunda operação, "2.0 Create Jira Issue", usamos essas variáveis globais em nossa transformação ("Create Issue") para gravar em nosso destino ("POST Jira Issue") onde salvamos a resposta da API para um variável global.
Analisar a resposta. Na terceira operação, "3.0 Parse Response", usamos essa resposta em uma fonte de variável global ("Response") e em nossa transformação ("Parse Create Issue Response") gravamos esses valores no log da operação.

Pedido e Resposta 1

Observe que qualquer outro destino pode ser usado e que o método e o que ele retorna dependem da API específica. Esse padrão pode ser modificado dependendo de como você gostaria de fornecer dados e usar os dados de resposta retornados da API.

Criar um Loop de Registros¶

Crie uma operação de transformação usando a fonte de dados que deseja usar em sua chamada de API. Para fins deste exemplo, criamos um script definindo a variável global source.csv com vários registros a serem usados e escrevi a variável global em uma fonte de variável global. Para uma implementação real, esse tipo de dados provavelmente viria de outro endpoint conectado; qualquer fonte pode ser usada.
```
<trans>
$source.csv = 'TEST,Research My API,Become familiar with my REST API endpoint.,High,Task
TEST,Add Missing Fields,Iterate using Postman to make sure all desired fields are generated.,Highest,Bug
TEST,Build Operations in Jitterbit,Use Jitterbit to design the REST API integration.,Medium,Task'
</trans>
```
Clique duas vezes no espaço reservado da transformação e crie uma nova transformação. Aqui é onde criaremos o loop para processar cada registro de origem individualmente.
1. Na etapa Nome do assistente de transformação, selecione o formato apropriado para sua origem e destino. Neste exemplo, selecionamos "Texto" para ambos, mas você pode usar qualquer formato.
2. Na etapa Source, você especifica a estrutura que está sendo usada para seus dados de origem. Como selecionamos um formato de texto, criamos um novo formato de arquivo para corresponder à estrutura de nossos dados. Se você usa um formato de arquivo ou outra estrutura, ele precisa corresponder à estrutura de seus dados de origem.
3. Na etapa Target é onde criaremos o loop. Para isso, você deve ter um campo que será usado para percorrer cada registro. Como usamos um formato de texto, criamos uma nova definição de formato de arquivo com um único campo.
No mapeamento de transformação, adicione um script de transformação no Loop campo e definir cada um dos campos de origem como variáveis globais. Mais tarde, adicionaremos um RunOperation() função no script para iniciar a próxima operação usando os dados de cada registro.
```
<trans>
$jira.key = key;
$jira.summary = summary;
$jira.description = description;
$jira.priority = priority;
$jira.issuetype = issuetype;
</trans>
```

Envie a Solicitação¶

Crie uma segunda operação de transformação, usando um destino HTTP com o HTTP Verb e URL para a solicitação de API específica. Se quiser usar a resposta recebida da API, em Opções, use o campo "Gravar resposta em (opcional)" para definir um destino de sua escolha. Neste exemplo, escrevemos a resposta retornada para uma variável global alvo com uma variável chamada "Resposta".
Na segunda operação, clique com o botão direito do mouse no espaço reservado de origem e selecione Remover do gráfico, pois usaremos um script para inserir registros como a origem em vez de definir uma origem de item de projeto para usar em a transformação.
Na segunda operação, clique duas vezes no espaço reservado da transformação e crie uma nova transformação. Aqui é onde forneceremos as estruturas de solicitação e resposta de amostra para que o Harmony saiba como processar os dados.
1. Na etapa Nome do assistente de transformação, selecione "Nenhum" para a fonte de dados, pois não estamos usando uma fonte tradicional para a operação. Selecione "JSON" para o destino dos dados, pois o Jira aceita solicitações neste formato.
2. Na etapa Destino, selecione a opção para criar uma nova estrutura a partir de um arquivo de amostra. Na próxima tela, forneça o arquivo de solicitação de amostra que você salvou da validação da API para esse tipo de solicitação e gere o XSD desse arquivo de amostra. Em nosso exemplo, geramos o XSD a partir do Jira_POST_CreateIssue_Request.json solicitação de amostra que salvamos anteriormente (consulte Validando uma API REST).

Na tela de mapeamento de transformação, você não deve ver uma estrutura no lado da origem. No lado do destino, criaremos um script de transformação em cada campo que desejamos mapear para fornecer dados para cada registro. Neste exemplo, usamos as variáveis globais que definimos anteriormente a partir de nossos dados de origem.

Campo Alvo	Script de Mapeamento
`json$fields$project$key$`	`<trans>` `$jira.key` `</trans>`
`json$fields$summary$`	`<trans>` `$jira.summary` `</trans>`
`json$fields$description$`	`<trans>` `$jira.description` `</trans>`
`json$fields$priority$name`	`<trans>` `$jira.priority` `</trans>`
`json$fields$issuetype$name`	`<trans>` `$jira.issuetype` `</trans>`

Enviar a Solicitação 1

Agora que a segunda operação foi criada, volte para o script de transformação no loop usado na primeira operação e adicione a função RunOperation() para executar a segunda operação que você acabou de criar. Isso fará com que cada registro seja processado pela primeira operação, a segunda operação seja executada para cada registro, efetivamente fazendo um loop em todos os registros.
```
<trans>
$jira.key = key;
$jira.summary = summary;
$jira.description = description;
$jira.priority = priority;
$jira.issuetype = issuetype;
RunOperation("<TAG>Operations/POST/2.0 Create Jira Issue</TAG>");
</trans>
```
Crie uma terceira operação que analisa a resposta da API que é executada após o sucesso da segunda operação. Para isso, clique com o botão direito no fundo da segunda operação e selecione On Success > Operation > Create New Operation e crie uma nova operação de transformação.
Na terceira operação, use como fonte sempre que você especificou a resposta da API a ser salva durante o destino HTTP configuração; no exemplo, usamos uma variável global. Para usar a mesma variável global como fonte, na árvore de itens do projeto, clique com o botão direito do mouse na variável global alvo e selecione Copiar para nova fonte para criar uma fonte de variável global usando a mesma variável global ($Response) como fonte.

Analisar a Resposta¶

Na terceira operação, use qualquer destino para o qual você gostaria de escrever a resposta. Para o exemplo, posteriormente escreveremos a resposta no log de operação em vez de um destino de item de projeto real. Clique com o botão direito do mouse no espaço reservado de destino e selecione Remover do gráfico.
Clique duas vezes no espaço reservado da transformação e crie uma nova transformação. Aqui é onde forneceremos as estruturas de solicitação e resposta de amostra para que o Harmony saiba como processar os dados.
1. Na etapa Nome do assistente de transformação, selecione "JSON" para a fonte de dados, pois estamos usando os dados de resposta de nossa API, que vem no formato JSON. Para o exemplo, selecionamos "JSON" como destino dos dados para escrever a resposta usando a mesma estrutura, mas você pode escolher qualquer tipo aqui, dependendo de como deseja gravar os dados.
2. Na etapa Source, selecione a opção para criar uma nova estrutura a partir de um arquivo de amostra. Na próxima tela, forneça o arquivo de resposta de amostra que você salvou da validação da API para esse tipo de solicitação e gere o XSD desse arquivo de amostra. Em nosso exemplo, geramos o XSD a partir do Jira_POST_CreateIssue_Response.json exemplo de resposta que salvamos anteriormente (consulte Validando uma API REST).
3. Na etapa Target, selecione o mesmo esquema que você acabou de gerar, pois estamos apenas passando pela resposta da API.
Na tela de mapeamento de transformação, mapeie todos os campos que deseja gravar. No exemplo, adicionamos um script de transformação no destino id campo que grava os valores retornados em variáveis globais que são então gravadas no log da operação. Você também pode colocar um script de transformação em cada campo de destino, mas como eles são usados apenas para gravar no log da operação, como um atalho, colocamos todos eles no script de um campo.
```
<trans>
$jira.id = json$id$;
$jira.key = json$key$;
$jira.link = json$self$;
WriteToOperationLog("Issue ID: " + $jira.id);
WriteToOperationLog("Issue Key: " + $jira.key);
WriteToOperationLog("Issue Link: " + $jira.link);
</trans>
```
Quando estiver pronto, implantar e execute a operação. Se a operação for bem-sucedida, clique com o botão direito do mouse na terceira operação e selecione Operation Log para confirmar que os registros foram gravados no log da operação. Como cada registro foi processado separadamente, haverá uma linha no log de operação para cada registro. Você também pode verificar o endpoint para ver se o novo registro foi criado ou fazer um GET no identificador do novo objeto.

Uma Estrutura de Solicitação Apenas¶

Esse padrão se aplica a métodos nos quais você fornece uma estrutura de solicitação, mas não há dados estruturados retornados pela API REST. Para APIs que possuem apenas uma estrutura de solicitação, isso não significa que a API não responde; isso significa que a resposta da API pode ser tão simples quanto um código de status.

Neste exemplo do padrão, fornecemos uma fonte para a solicitação em uma transformação ("Edit Issue") e, em seguida, fazemos uma solicitação usando um método PUT ("PUT Jira Issue") para atualizar e adicionar vários campos em um único registro. Assim como no POST, pode ser comum que uma API específica permita a atualização de apenas um registro por vez. Para percorrer os dados, consulte a parte de loop do padrão anterior para Both Request and Response Structures.

Uma estrutura de solicitação apenas 1

Se o código de status estiver na faixa de 200, o Harmony o reportará como bem-sucedido. Para outros códigos que indiquem erros, o código retornado será informado no log da operação. Se você receber um erro, também poderá configurar cadeias de operação para serem executadas em caso de falha (por exemplo, para enviar uma mensagem ou e-mail do Slack informando que a operação não foi bem-sucedida).

Crie uma operação de transformação usando um destino HTTP com o HTTP Verb e URL para a solicitação de API específica.
Na operação, use uma fonte apropriada para seu caso de uso. No exemplo, como forneceremos os dados de origem em um script, clique com o botão direito do mouse no espaço reservado de origem e selecione Remove From Graph.
Na operação, clique duas vezes no espaço reservado da transformação e crie uma nova transformação. Aqui é onde forneceremos a estrutura de solicitação de amostra.
1. Na etapa Nome do assistente de transformação, selecione o formato de sua fonte e destino de dados. No exemplo, selecionamos "(None)" para a fonte de dados, pois não estamos usando uma fonte tradicional para a operação. Selecionamos "JSON" para o destino dos dados, pois o Jira aceita solicitações neste formato. Se você precisar repetir vários registros de origem, consulte a parte do loop do padrão anterior para Both Request and Response Structures.
2. Na etapa Destino, selecione a opção para criar uma nova estrutura a partir de um arquivo de amostra. Na próxima tela, forneça o arquivo de solicitação de amostra que você salvou da validação da API para esse tipo de solicitação e gere o XSD desse arquivo de amostra. Em nosso exemplo, geramos o XSD a partir do Jira_PUT_EditIssue_Request.json solicitação de amostra que salvamos anteriormente (consulte Validando uma API REST).
Na tela de mapeamento de transformação, você não deve ver uma estrutura no lado da origem. No lado do destino, criaremos um script de transformação em cada campo que desejamos mapear para fornecer dados para cada campo. Neste exemplo, codificamos os valores para a atualização para adicionar um comentário, alterar a prioridade e adicionar um rótulo. Para esta solicitação, o ID do objeto é fornecido na URL, então não estamos mapeando nenhuma chave aqui. Para obter um exemplo de mapeamento usando variáveis, consulte o padrão anterior para Both Request and Response Structures.
Quando estiver pronto, implantar e execute a operação. Clique duas vezes no(s) ícone(s) de status no monitor de operação para visualizar informações sobre o status da operação. Se o código de status estiver na faixa de 200, o Harmony informará que a operação foi concluída com sucesso. Você também pode verificar seu endpoint ou fazer outro GET para ver se as atualizações foram feitas.

Se houver outros códigos de status, cabeçalhos de resposta ou qualquer mensagem de erro retornada da API, eles serão relatados.

Nem uma Solicitação Nem uma Estrutura de Resposta¶

Esse padrão se aplica a métodos que não aceitam dados de entrada estruturados nem retornam dados de saída estruturados. Nesses casos, a solicitação geralmente é especificada inteiramente com a URL e os cabeçalhos da solicitação; a resposta é normalmente um código de status.

Neste exemplo do padrão, fazemos uma requisição utilizando o método DELETE, onde apagamos os registros que foram criados e atualizados nos padrões anteriores, utilizando o ID do objeto (chave de emissão do Jira). Para minimizar o número de peças necessárias, esta operação é feita inteiramente dentro de um script ("Delete Issue"). Embora o script neste padrão esteja incluído em sua própria operação, ele também pode ser referenciado em um script de transformação incluído em outra operação (por exemplo, em um nó de loop para excluir registros que atendem a determinadas condições).

Nem um Pedido nem uma Estrutura de Resposta 1

Crie um destino HTTP com o HTTP Verb e URL para a solicitação de API específica. Lembre-se de limpar o tipo de conteúdo, pois nenhum dado estruturado está sendo enviado para a API.
Crie uma operação de script com um novo Jitterbit Script que fornece o registro a ser excluído (substituindo a variável do projeto que definimos anteriormente) chama o destino HTTP que acabamos de criar para enviar a solicitação.
```
<trans>
$jira.issueKey = "TEST-11";
WriteFile("<TAG>Targets/DELETE Jira Issue</TAG>", "");
</trans>
```
Implante e execute a operação. Clique duas vezes no(s) ícone(s) de status no monitor de operação para visualizar informações sobre o status da operação. Se a operação não for bem-sucedida, o código de status, os cabeçalhos de resposta e quaisquer mensagens de erro retornadas da API serão relatados no log da operação. Você também pode verificar em seu endpoint ou confirmar se os registros foram excluídos fazendo um GET.