Publicar uma operação como uma API no Jitterbit Studio

Introdução

Esta página descreve como configurar e publicar uma API personalizada (para expor uma operação para consumo) no Studio. A opção Publicar como uma API está acessível no menu de ações de uma operação.

Alternativamente, APIs personalizadas podem ser criadas no API Manager usando a interface ou o Assistente de IA.

Para um guia orientado por tarefas sobre como publicar uma operação como uma API REST, incluindo configuração de resposta e segurança, consulte Expor uma operação do Studio como uma API REST.

APIs personalizadas (publicadas e rascunho) são exibidas nestes locais:

• A página APIs do API Manager.
• A aba Recursos do painel de projetos para o projeto do Studio associado à API personalizada.

Pré-requisitos

Para usar a opção Publicar como uma API no menu de ações da operação, estes pré-requisitos devem ser atendidos:

• A organização sendo acessada deve ter uma subscrição ao API Manager e ter as permissões de função e níveis de acesso ao ambiente apropriados. Para informações sobre como adicionar o API Manager à sua licença, entre em contato com seu Gerente de Sucesso do Cliente (CSM).

• A operação não deve ter nenhuma alteração não implantada.

Configurar a API

Após clicar na opção Publicar como uma API no menu de ações da operação, um painel de configuração de API abre na parte inferior do designer de projetos. As cinco etapas do processo de configuração são descritas abaixo:

Perfil

Digite as seguintes informações básicas sobre a API.

• Nome da API: Digite um nome para a API a ser usado para fins de identificação interna.

• Raiz do Serviço: O nome público da API a ser usado como parte da URL do serviço da API. Por padrão, este campo é preenchido com o nome da operação convertido para camel case. Este campo não permite espaços ou certos caracteres especiais. Não é recomendado usar caracteres especiais diferentes de um sublinhado (_). Estes caracteres especiais são permitidos:

  _ ~ ( ) $ ; / \ ? : @ = & ' ! * @ , + -

• Descrição: Digite uma descrição opcional para a API.

• Ambiente: Este campo é definido como o ambiente do projeto sendo acessado no momento e não pode ser alterado.

• Número da versão: Digite uma versão opcional a ser usada como parte da URL do serviço da API. Este campo permite um máximo de 50 caracteres e não permite espaços ou certos caracteres especiais. Não é recomendado usar caracteres especiais diferentes de um ponto (.) ou um hífen (-). As convenções de nomenclatura comuns incluem versões incrementais, como v1.0, v1.1, v1.2, ou usar uma data em que a API foi publicada, como 2023-09-21.

Configurações

Continue configurando a API. Essas configurações são opcionais.

• Timeout: Insira o número de segundos antes da API expirar. O padrão é 30 segundos. O máximo é 180 segundos.

  Nota

  Essa configuração é independente da configuração Operation time out disponível na guia Options da operação. As configurações de timeout da operação não são usadas para APIs do API Manager, a menos que um agente privado seja usado e a configuração EnableAPITimeout no arquivo de configuração do agente privado esteja ativada.

• SSL only: Essa opção é ativada por padrão e requer o uso de criptografia SSL (recomendado).

• CORS: Ative para habilitar Cross-Origin Resource Sharing (CORS) (não recomendado). Ativar essa opção exibe a seguinte mensagem:

  Texto do diálogo

  Habilitar CORS
  Permitir que qualquer origem acesse uma API não é recomendado devido a possíveis riscos de segurança. Uma preocupação importante é que isso faz com que a operação atribuída ao método OPTIONS seja executada sem autenticação. Antes de habilitar essa configuração, confirme se ela está alinhada com as políticas de segurança da sua organização.

  Para mais informações, consulte Cross-Origin Resource Sharing no MDN.

  
  ContinuarCancelar

• Verbose logging: Ative para habilitar o registro detalhado. Os registros detalhados para APIs incluem dados de solicitação e resposta em cada log de API para ajudar a monitorar dados de entrada e saída e facilitar a depuração. Como isso pode criar arquivos de log grandes, o registro detalhado é desativado por padrão. Ativar essa opção exibe a seguinte mensagem:

  Texto do diálogo

  Habilitar registro detalhado
  O registro detalhado para APIs permite que o usuário decida se cada log de API deve conter dados de solicitação e resposta. Essa funcionalidade ajuda a monitorar dados de entrada/saída e depurar problemas de API.

  
  ContinuarCancelar

• Enable debug mode until: Selecione para habilitar o modo de depuração e insira uma data e hora correspondentes em que o modo de depuração será desativado. O tempo máximo de ativação é de duas semanas. Ativar essa opção exibe a seguinte mensagem:

  Texto do diálogo

  Habilitar modo de depuração
  O modo de depuração habilita o rastreamento completo de todas as solicitações recebidas por essa URL. Quando ativado, o sistema captura o conteúdo completo de cada solicitação e resposta de API por até 24 horas. Isso inclui todas as operações acionadas pela API. Devido ao alto volume de dados gerados e ao possível impacto no armazenamento, o modo de depuração pode ser ativado por no máximo duas semanas.

  
  ContinuarCancelar

Serviços

Configure serviços para sua API.

• Service Name: Insira um nome para o serviço de API. Por padrão, esse campo é definido como o nome da operação.

• Method: Selecione entre ALL, CUSTOM, DELETE, GET, POST ou PUT como o método de solicitação a ser usado para a operação selecionada. Selecionar ALL criará métodos de solicitação separados DELETE, GET, POST e PUT para a operação (o método CUSTOM não está incluído).

  Nota

  Serviços de API que usam um método CUSTOM não terão documentação OpenAPI gerada através da página Portal Manager devido a uma limitação da especificação OpenAPI.

• Caminho: O caminho da solicitação.

• Projeto: (Visível apenas para APIs personalizadas e APIs OData.) O nome do projeto do Studio.

• Operação a Disparar: (Visível apenas para APIs personalizadas e APIs OData.) O nome da operação sendo chamada.

• Tipo de Resposta: (Visível apenas para APIs personalizadas e APIs OData.) Este campo é obrigatório. Selecione um de Destino Final, Variável do Sistema ou Sem Resposta:

  • Destino Final: A resposta da API é o destino final da operação. Quando este tipo de resposta é selecionado, a operação deve ter (como destino final da cadeia de operações) uma atividade API Response do Studio. Se qualquer outro destino final for usado, a resposta da API estará vazia.

  • Variável do Sistema: A resposta da API é definida em uma variável Jitterbit na operação. Quando este tipo de resposta é selecionado, a operação deve ter (como parte de uma cadeia de operações) um script que define a variável Jitterbit jitterbit.api.response igual à resposta que você deseja que a API retorne. Se esta variável não for definida, a resposta da API estará vazia.

  • Sem Resposta: A resposta da API está em branco. Se a solicitação para executar a operação selecionada for aceita, a API retornará uma resposta vazia imediata com código HTTP 202.

• Ações: Passe o mouse sobre a linha do serviço para revelar ações adicionais:

  • Copiar URL do serviço de API: Clique para copiar a URL do serviço de API para sua área de transferência. (Você verá uma confirmação da ação.)

  • Ir para Serviço de API: Abre a página Resumo e Confirmação da API, onde você pode editar as configurações da API.

  • Duplicar: (Visível apenas para APIs personalizadas e APIs OData.) Cria uma duplicata do serviço de API. Você deve alterar o método de solicitação ou o Caminho, pois cada serviço de API deve ter uma combinação única desses campos.

  • Excluir: Exclui o serviço de API.

Quando você clica em uma linha de serviço de API personalizada, estas abas aparecem:

Aba Parâmetros de Caminho

Quando parâmetros de solicitação são incluídos no Caminho, esta aba é preenchida com estes campos:

• Parâmetro: Exibe os parâmetros de solicitação definidos no Caminho.

• Descrição: Opcionalmente, insira uma descrição para os parâmetros de solicitação.

Aba Parâmetros de Consulta

Esta aba permite adicionar parâmetros de consulta ao serviço de API:

• Adicionar Parâmetro: Clique para adicionar um parâmetro de consulta ao serviço de API. Quando clicado, estes campos ficam disponíveis:

  • Parâmetro: Insira o nome do parâmetro de consulta.

  • Descrição: Opcionalmente, insira a descrição do parâmetro de consulta.

  • Excluir: Clique no ícone de exclusão ao lado de um parâmetro de consulta para excluir esse parâmetro.

Aba Cabeçalhos

Esta aba permite adicionar cabeçalhos de solicitação ao serviço de API:

• Adicionar Parâmetro: Clique para adicionar um cabeçalho de solicitação ao serviço de API. Quando clicado, estes campos ficam disponíveis:

  • Parâmetro: Insira o nome do cabeçalho de solicitação.

  • Descrição: Opcionalmente, insira a descrição do cabeçalho de solicitação.

  • Obrigatório: Selecione se o cabeçalho de solicitação deve ser obrigatório para cada solicitação do serviço de API.

  • Excluir: Exclui o cabeçalho de solicitação.

Perfis de segurança

Configure perfis de segurança para a API. Estas configurações são opcionais.

• Pesquisar: Digite qualquer parte do nome do perfil de segurança, tipo ou nome de usuário na caixa de pesquisa para filtrar a lista de serviços. Use apenas caracteres alfanuméricos. A pesquisa não diferencia maiúsculas de minúsculas.

• Novo perfil de segurança: Abre um painel para configurar um novo perfil de segurança (consulte Perfis de Segurança):

  

A lista de perfis de segurança existentes para escolher mostra-os em uma tabela com as seguintes colunas:

• Atribuir: Use a alternância para atribuir ou desatribuir o perfil de segurança à API.

  Regras de atribuição de perfil de segurança

  • Múltiplos perfis: Você pode atribuir vários perfis de segurança com o mesmo tipo de autenticação a uma API. Apenas os tipos de autenticação basic e API key podem ser usados juntos.

  • Alterações de publicação: Quando você desatribui um perfil de segurança de uma API usando a alternância, a alteração é salva como rascunho. Você deve publicar a API para que a alteração entre em vigor. Até que a API seja publicada, o perfil de segurança ainda é considerado "em uso" e não pode ser excluído da página Perfis de Segurança.

• Nome do Perfil: O nome do perfil de segurança.

• Tipo: O tipo de autenticação, um de Anônimo, Chave de API, Básico ou OAuth 2.0.

• Nome de Usuário: Exibe o nome de usuário para qualquer perfil de segurança usando autenticação Básica. Caso contrário, o tipo de autenticação é exibido.

• Ações: Passe o mouse sobre a linha do perfil de segurança para revelar uma ação adicional:

  • Ir para perfil de segurança: Abre a tela de configuração do perfil de segurança.

Funções de usuário

Configure funções da organização cujos membros têm acesso à API. Essas configurações são opcionais.

Você pode classificar a tabela por Função de Usuário clicando na linha de cabeçalho respectiva.

• Pesquisar: Digite qualquer parte da função de usuário, permissão ou status na caixa de pesquisa para filtrar a lista de serviços. Use apenas caracteres alfanuméricos. A pesquisa não diferencia maiúsculas de minúsculas.

• Nova função de usuário: Abre um painel para configurar uma nova função de usuário:

  

  • Nome da função: Digite um nome exclusivo para a função.

  • Permissões: Clique para abrir o menu e selecione pelo menos uma permissão da lista.

    Regras de gerenciamento de funções

    Estas regras se aplicam ao gerenciar funções em APIs:

    • Usuários com permissão Admin ou acesso ao ambiente Write podem atribuir ou desatribuir funções a APIs.
    • Usuários com permissão Admin podem criar e atribuir novas funções.
    • Usuários com permissão Admin não podem ser desatribuídos de nenhuma API por nenhum usuário.

  • Salvar: Salva a função e a adiciona à tabela de funções.

  • Cancelar: Fecha o painel sem salvar as alterações.

• Permissões: As permissões que um usuário tem atualmente.

• Status: Exibe se a função de usuário está atribuída ou não atribuída à API.

• Ações: Passe o mouse sobre a linha da função de usuário para revelar uma ação adicional:

  • Ir para função de usuário: Abre a página Gerenciamento de Usuários do Console de Gerenciamento.

Rodapé

O rodapé do painel mostra estas opções. Elas podem ser ativadas ou desativadas dependendo de quanto você já configurou:

• Cancelar: Fecha o diálogo sem salvar.

• Anterior: Retorna à etapa anterior.

• Próximo: Avança para a próxima etapa.

• Salvar como rascunho: Salva a API com status Rascunho e fica acessível na página APIs do API Manager. Uma API em rascunho não conta como uma URL de API contra sua cota de assinatura do Harmony. Você pode acessar e concluir a configuração da API em rascunho na página APIs do API Manager.

• Publicar: Salva a API com status Publicada. A API fica ativa e acessível em até cinco minutos. Uma API publicada conta como uma URL de API contra sua cota de assinatura do Harmony. Você pode acessar a API publicada na página APIs do API Manager.