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

Alternativamente, é possível criar APIs personalizadas no API Manager usando a interface ou o Assistente de IA.

Para um passo a passo 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.

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

• A página APIs do API Manager.
• A aba Recursos do painel de projetos do 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, é necessário atender a estes pré-requisitos:

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

• A operação não deve ter alterações não implantadas.

Configurar a API

Depois de clicar na opção Publicar como uma API no menu de ações da operação, uma gaveta de configuração de API abre ao longo da parte inferior do designer de projetos. As cinco etapas do processo de configuração estão descritas abaixo:

Perfil

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

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

• Raiz do Serviço: O nome público da API para usar como parte da URL do serviço da API. Por padrão, este campo é preenchido com o nome da operação convertido para camelCase. Este campo não permite espaços ou certos caracteres especiais. Não é recomendável usar caracteres especiais além de um sublinhado (_). Estes caracteres especiais são permitidos:

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

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

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

• Número da versão: Insira uma versão opcional para usar 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 é recomendável usar caracteres especiais além 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 usando uma data em que a API foi publicada, como 2023-09-21.

Configurações

Continue configurando a API. Estas 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

  Esta configuração é independente da configuração Operation time out disponível na guia Options da operação. As configurações de timeout de 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: Esta opção está ativada por padrão e requer o uso de criptografia SSL (recomendado).

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

  Texto do diálogo

  Habilitar CORS
  Permitir que qualquer origem acesse uma API não é recomendado devido aos 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 de 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 está desativado por padrão. A ativação desta opção exibe a seguinte mensagem:

  Texto do diálogo

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

  
  ContinuarCancelar

• Enable debug mode until: Selecione para ativar o modo de depuração e inserir uma data e hora correspondente quando o modo de depuração será desativado. O período máximo de ativação é de duas semanas. A ativação desta opção exibe a seguinte mensagem:

  Texto do diálogo

  Habilitar modo de depuração
  O modo de depuração ativa o rastreamento completo para todas as solicitações recebidas por esta 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 impacto potencial no armazenamento, o modo de depuração pode ser ativado apenas por até duas semanas.

  
  ContinuarCancelar

Serviços

Configure os serviços para sua API.

• Service Name: Insira um nome para o serviço de API. Por padrão, este campo é definido com 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 DELETE, GET, POST e PUT separados para a operação (o método CUSTOM não é incluído).

  Nota

  Serviços de API que usam um método CUSTOM não terão documentação do OpenAPI gerada por meio da página Portal Manager devido a uma limitação da especificação do 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 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 destino final da cadeia de operações) uma atividade de Resposta da API 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 fica 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 cursor 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 a 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 exclusiva 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, digite 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: Digite o nome do parâmetro de consulta.

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

  • Excluir: Clique no ícone de exclusão próximo a 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: Digite o nome do cabeçalho de solicitação.

  • Descrição: Opcionalmente, digite 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 uma gaveta 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 o botão de alternância para atribuir ou desatribuir o perfil de segurança à API.

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

  • Vários perfis: É possível atribuir vários perfis de segurança com o mesmo tipo de autenticação a uma API. Apenas os tipos de autenticação básico e chave de API podem ser usados juntos.

  • Publicação de alterações: Ao desatribuir um perfil de segurança de uma API usando o botão de alternância, a alteração é salva como rascunho. É necessário 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 todos os perfis de segurança que usam 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 de organização cujos membros têm acesso à API. Essas configurações são opcionais.

É possível classificar a tabela por Função de Usuário clicando na linha de cabeçalho correspondente.

• 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 uma gaveta 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 selecione pelo menos uma permissão da lista.

    Regras de gerenciamento de funções

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

    • Usuários com permissão Admin ou acesso ao ambiente Gravação 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 a gaveta 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é da gaveta mostra essas opções. Elas podem ser habilitadas ou desabilitadas dependendo de quanto já foi configurado:

• Cancelar: Fecha o diálogo sem salvar.

• Anterior: Volta à 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 API URL na sua franquia 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 Publicado. A API fica ativa e acessível em cinco minutos. Uma API publicada conta como uma API URL na sua franquia de assinatura do Harmony. Você pode acessar a API publicada na página APIs do API Manager.