Conecte-se a uma API REST¶

Introdução¶

Esta página mostra como usar as informações da validação de uma API REST para conectar-se à API no Harmony. Esta página continua o Tutorial da API REST usando API REST do Atlassian Jira Cloud v2 como exemplo, usando as informações coletadas após Pesquisando uma API REST e validado em Validando uma API REST.

A conexão com a API dentro do Harmony é configurada através do Design Studio. Ao contrário dos serviços da Web baseados em WSDL, um assistente que orienta a configuração não está disponível. Em vez disso, uma conexão com uma API REST é configurada configurando uma origem HTTP ou um destino HTTP. Posteriormente, você usará a origem ou o destino HTTP em uma operação conforme descrito em Usando uma API REST em operações.

Embora este tutorial se concentre apenas nas opções de configuração comuns, usuários experientes e inexperientes são incentivados a revisar as páginas Fonte HTTP e Destino HTTP, que fornecem informações mais detalhadas sobre todas as opções disponíveis para configuração.

Configurar uma Origem Ou Destino HTTP¶

Um exemplo de configuração usando o exemplo do Jira é fornecido abaixo, seguido por subseções que descrevem partes específicas da configuração de origem/destino HTTP. Consulte a documentação de Fonte HTTP e Destino HTTP sobre como criar uma origem ou destino, bem como todas as opções configuráveis disponíveis.

Verbo HTTP e URL¶

Durante a configuração, selecione o Verbo HTTP apropriado para sua solicitação e forneça o mesmo URL que você usou como URL de solicitação no Postman.

Para tornar a URL dinâmica, você pode usar variáveis de projeto ou globais no lugar de um URL base ou para adicionar parâmetros de consultar.

Se variáveis forem usadas, você também poderá fornecer valores padrão (conforme mostrado entre chaves) para fins de teste ou padrão. (Se os valores padrão não forem fornecidos, o teste da conexão poderá falhar, mas como os valores das variáveis serão preenchidos em tempo de execução, a operação ainda deverá ser bem-sucedida em tempo de execução).

Por exemplo, para nosso PUT "Editar problema" do Jira, nosso URL é construído como:

https://[jira.baseUrl{my-domain.atlassian.net}]/rest/api/2/issue/[jira.issueKey{TEST-11}]

Autenticação¶

A configuração de autenticação irá variar para diferentes métodos de autenticação.

No exemplo, como estamos usando autenticação básica, preenchemos o mesmo Login e Senha que usamos para teste (também empregando variáveis de projeto) e expandiu Opções para marcar a caixa de seleção Usar autenticação HTTP básica.

Você deve usar o tipo de autenticação configurado para seu endpoint específico. Por exemplo, se você estivesse usando autenticação negociada, como em um servidor Windows que possui autenticação integrada, você preencheria Login e Senha, mas não marcaria a caixa de seleção para autenticação básica.

Como outro exemplo, se você estivesse usando autenticação baseada em token, você poderia deixar essas credenciais em branco e, em vez disso, fornecer um projeto ou variável global token de autenticação nos cabeçalhos de solicitação em Opções > Propriedades avançadas. Uma configuração típica baseada em token é descrita em Transformação REST - Sugar CRM - Solicitar token de sessão.

Cabeçalhos¶

Em Propriedades avançadas também é onde você forneceria quaisquer cabeçalhos de solicitação adicionais ainda não cobertos na interface de origem/destino HTTP. Para cada chamada, é recomendável verificar os cabeçalhos da solicitação ao validar a API para ter certeza de que você possui todos os cabeçalhos de solicitação necessários.

Ao fornecer cabeçalhos de solicitação com a caixa Propriedades avançadas "Cabeçalhos de solicitação (uma linha por cabeçalho)", observe que o auxílio de preenchimento automático padrão para variáveis no Design Studio não funciona nesta área. Ou seja, quando você começa a digitar um colchete aberto ([), você não verá opções de variáveis existentes. No entanto, é útil saber que você ainda pode usar variáveis de projeto ou globais nesta área.

Os cabeçalhos de resposta, por outro lado, não são validados no Harmony. No entanto, se precisar usar algo fornecido no cabeçalho de resposta da API, você pode usar a variável Jitterbit apropriada para uma origem ou destino HTTP:

• Fonte HTTP: $jitterbit.source.http.response.header.*

• Meta HTTP: $jitterbit.target.http.response.header.*

A documentação para essas variáveis é fornecida em Source Jitterbit Variables e Variáveis de Jitterbit alvo.

Tipo de Conteúdo¶

Para destinos HTTP, em Opções, verifique se o tipo de conteúdo corresponde ao formato esperado pela API. Observe que esta opção é aplicável apenas ao formato da estrutura de solicitação (não à estrutura de resposta).

É comum que APIs REST aceitem solicitações e forneçam respostas em JSON, como é o caso do nosso exemplo da API Jira. Neste exemplo, desmarcamos a caixa de seleção de um tipo de conteúdo padrão de text/plain e inseriu um tipo de conteúdo personalizado de application/json.

Se você estiver fornecendo uma solicitação de API REST em um formato diferente, especifique o tipo de conteúdo adequadamente. Caso o método não aceite dados estruturados, desmarque a caixa de seleção e deixe este campo em branco.

Resposta¶

Para um destino HTTP que usa uma solicitação que fornece uma resposta que você gostaria de gravar em outro destino, configure isso em Opções.

Qualquer tipo de destino pode ser usado aqui. Em nosso exemplo para o POST "Criar problema" do Jira, optamos por escrever a resposta para um destino da variável global usando uma variável global chamada "Resposta". Para conjuntos de dados maiores que 4 MB, é recomendado usar armazenamento temporário em vez de usar uma variável global (consulte Variável Global versus Armazenamento Temporário).

Conexão de Teste¶

Depois de concluir a configuração, clique em Testar conexão para verificar se o Harmony pode se conectar à sua API REST.

Para uma fonte HTTP, se for bem-sucedido, você deverá receber de volta o arquivo com o nome da URL. Observe que você não pode ler o conteúdo do arquivo aqui; testar a conexão apenas verifica se você está recebendo algo da API. Mais tarde, depois de usar a fonte em uma operação, você poderá usar o conteúdo, se desejar.

Para um destino HTTP, se for bem-sucedido, a mensagem simplesmente indicará que a conexão foi bem-sucedida.

Se a conexão falhar usando o mesmo URL de solicitação e método de autenticação que você testou com êxito no Postman, o problema provavelmente estará na configuração da origem ou destino HTTP no Design Studio. Consulte a documentação em Fonte HTTP e Destino HTTP e verifique sua configuração.

Próximos Passos¶

Depois de configurar uma origem ou destino HTTP, a próxima etapa é Usar uma API REST em operações. Embora cada API REST siga as mesmas restrições arquitetônicas, nem todas são projetadas da mesma maneira para cada método HTTP. Como cada solicitação e resposta específica depende da API específica, na próxima etapa apresentamos quatro padrões de design para projetar operações.