Publique 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) a partir do Studio. A opção Publicar como uma API está acessível a partir do menu de ações da operação.

Alternativamente, APIs personalizadas podem ser criadas a partir do API Manager usando a UI ou o Assistente de IA.

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

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

Pré-requisitos

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

• A organização acessada deve ter uma assinatura do 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 mudança 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 da API se abre na parte inferior do designer do projeto. Os cinco passos do processo de configuração são descritos abaixo:

Perfil

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

• Nome da API: Insira 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. O uso de caracteres especiais além de um sublinhado (_) não é recomendado. Os seguintes caracteres especiais são permitidos:

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

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

• Ambiente: Este campo é definido para o ambiente do projeto atualmente acessado e não pode ser alterado.

• Número da versão: Insira 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. O uso de caracteres especiais além de um ponto (.) ou um hífen (-) não é recomendado. Convenções comuns de nomenclatura incluem versões incrementais, como v1.0, v1.1, v1.2, ou usando uma data em que a API foi publicada, como 2023-09-21.

Configurações

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

• Tempo limite: Insira o número de segundos antes que a API atinja o tempo limite. O padrão é 30 segundos. O máximo é 180 segundos.

  Nota

  Esta configuração é independente da configuração de Tempo limite da operação disponível na aba Opções da operação. As configurações de tempo limite da operação não são usadas para APIs do Gerenciador de API, a menos que um agente privado seja utilizado e a configuração EnableAPITimeout no arquivo de configuração do agente privado esteja habilitada.

• Apenas SSL: Esta opção está ativada por padrão e requer o uso de criptografia SSL (recomendado).

• CORS: Ative para habilitar Compartilhamento de Recursos entre Diferentes Origens (CORS) (não recomendado). Ativar este toggle exibe a seguinte mensagem:

  Texto do diálogo

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

  Para mais informações, veja Compartilhamento de Recursos entre Diferentes Origens no MDN.

  
  ContinuarCancelar

• Registro detalhado: Ative para habilitar o registro detalhado. Registros detalhados para APIs incluem dados de solicitação e resposta em cada registro 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 está desativado por padrão. Ativar este toggle exibe a seguinte mensagem:

  Texto do diálogo

  Habilitar registro detalhado
  O registro detalhado para APIs permite que o usuário decida se cada registro 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

• Habilitar modo de depuração até: Selecione para habilitar o modo de depuração e habilitar a entrada de uma data e hora correspondentes em que o modo de depuração será desativado. O tempo máximo de habilitação é de duas semanas. Ativar este toggle exibe a seguinte mensagem:

  Texto do diálogo

  Ativar modo de depuração
  O modo de depuração ativa o rastreamento completo para todas as solicitações recebidas através desta URL. Quando ativado, o sistema captura o conteúdo completo de cada solicitação e resposta da API por até 24 horas. Isso inclui todas as operações acionadas pela API. Devido ao alto volume de dados gerados e ao impacto potencial no armazenamento, o modo de depuração pode ser ativado por até duas semanas.

  
  ContinuarCancelar

Serviços

Configure os serviços para sua API.

• Nome do Serviço: Insira um nome para o serviço da API. Por padrão, este campo é definido como o nome da operação.

• Método: Selecione entre TODOS, PERSONALIZADO, EXCLUIR, OBTER, POSTAR ou ATUALIZAR como o método de solicitação a ser usado para a operação selecionada. Selecionar TODOS criará métodos de solicitação separados EXCLUIR, OBTER, POSTAR e ATUALIZAR para a operação (o método PERSONALIZADO não está incluído).

  Nota

  Os serviços da API que utilizam um método PERSONALIZADO 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 para a solicitação.

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

• Operação a Acionar: (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.) Selecione entre 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 o destino final da cadeia de operações) uma atividade de Resposta da API do Studio. Se qualquer outro destino final for utilizado, a resposta da API ficará vazia.

• Variável do Sistema: A resposta da API é definida em uma variável Jitterbit na operação. Quando esse 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 essa variável não for definida, a resposta da API ficará vazia.

• Sem Resposta: A resposta da API está em branco. Se o pedido para executar a operação selecionada for aceito, a API retornará uma resposta vazia imediata com o 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 API: Clique para copiar o URL do serviço API para sua área de transferência. (Você verá uma confirmação da ação.)

  • Ir para o Serviço API: Abre a página Resumo & Confirmação para a 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 API. Você deve alterar ou o método de solicitação ou o Caminho, pois cada serviço API deve ter uma combinação única desses campos.

  • Excluir: Exclui o serviço API.

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

Aba de parâmetros de caminho

Quando parâmetros de solicitação estão incluídos no Caminho, esta aba é preenchida com esses 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 de parâmetros de consulta

Esta aba permite que você adicione parâmetros de consulta ao serviço API:

• Adicionar Parâmetro: Clique para adicionar um parâmetro de consulta ao serviço da API. Quando clicado, esses 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 de Cabeçalhos

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

• Adicionar Parâmetro: Clique para adicionar um cabeçalho de solicitação ao serviço da API. Quando clicado, esses 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 de serviço da API.

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

Perfis de Segurança

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

• Pesquisar: Insira 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 (veja 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 o botão alternar 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 múltiplos 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.

  • Publicação de alterações: Quando você desatribui um perfil de segurança de uma API usando o botão alternar, a alteração é salva como um rascunho. Você deve publicar a API para que a alteração tenha efeito. 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 quaisquer perfis de segurança que utilizam 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 o perfil de segurança: Abre a tela de configuração para o 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 respectiva linha do cabeçalho.

• 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 único para a função.

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

    Regras de gerenciamento de funções

    Essas regras se aplicam ao gerenciamento de funções em APIs:

    • Usuários com Admin permissão ou Acesso de Escrita acesso ao ambiente podem atribuir ou desatribuir funções às APIs.
    • Usuários com Admin permissão podem criar e atribuir novas funções.
    • Usuários com Admin permissão 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 possui atualmente.

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

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

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

Rodapé

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

• Cancelar: Fecha o diálogo sem salvar.

• Anterior: Retorna ao passo anterior.

• Próximo: Avança para o próximo passo.

• Salvar como rascunho: Salva a API no status Rascunho e é acessível a partir da página APIs do Gerenciador de APIs. Uma API em rascunho não conta como um URL de API contra sua cota de assinatura do Harmony. Você pode acessar e completar a configuração da API em rascunho a partir da página APIs do Gerenciador de APIs.

• Publicar: Salva a API no status Publicada. A API está ao vivo e acessível em cinco minutos. Uma API publicada conta como um URL de API contra sua cota de assinatura do Harmony. Você pode acessar a API publicada a partir da página APIs do Gerenciador de APIs.