Ir para o conteúdo

Configuração de API personalizada no Jitterbit API Manager

Introdução

Esta página descreve como criar e configurar uma API personalizada na página de APIs do Jitterbit API Manager. APIs personalizadas são um dos três tipos de APIs configurados através do API Manager. Para os outros dois tipos — serviço OData e API proxy — consulte a configuração do serviço OData e a configuração da API proxy.

Alternativamente, APIs personalizadas podem ser criadas no Integration Studio usando a opção Publicar como uma API acessada a partir do menu de ações de uma operação.

Nota

Uma vez publicada, cada API personalizada conta como uma URL de API contra sua cota de assinatura do Harmony.

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

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

Pré-requisitos

Como uma API personalizada expõe uma operação do Harmony para consumo, tal operação deve primeiro ser criada e implantada no Harmony. A operação existente é então referenciada durante a configuração da API personalizada. A operação que uma API personalizada aciona pode ser uma operação do Integration Studio ou do Design Studio.

Para instruções sobre como criar e implantar uma operação, consulte estes recursos:

Criar uma nova API personalizada

Quando você acessa a página APIs do Gerenciador de API, se não houver APIs personalizadas, serviços OData ou APIs proxy na organização selecionada, esta tela estará em branco.

Para criar uma nova API personalizada, clique em Novo > API Personalizada:

sem APIs nova API

Ao clicar em Nova API, a tela de configuração da API personalizada é aberta. Detalhes sobre como configurar uma nova API personalizada são fornecidos em Configurar uma API personalizada abaixo.

Configurar uma API personalizada

A tela de configuração inclui quatro etapas de configuração, cada uma coberta abaixo:

A URL do serviço de uma API é a URL usada para consumir a API usando um método de autenticação configurado. As partes da URL do serviço de uma API são descritas em Introdução ao Gerenciador de API em URL do serviço da API.

A URL do Serviço é exibida na parte superior de cada etapa após a conclusão da etapa 1:

publicar nova API etapa 1 configurações URL do serviço

Etapa 1: Configurações

publicar nova API etapa 1 configurações

  • Nome da API: Insira um nome para a API a ser usado para fins de identificação interna. Os seguintes caracteres especiais são permitidos:

    ( ) - _

  • Ambiente: Use o menu para selecionar o ambiente onde a API residirá. Você pode digitar qualquer parte do nome do ambiente no menu para filtrar a lista de ambientes. Os resultados do menu são filtrados em tempo real a cada tecla pressionada.

    Nota

    Após a criação da API, o ambiente não pode ser alterado. Para mover uma API entre ambientes, você pode clonar a API ou exportar e importar a API em outro ambiente.

  • Raiz do serviço: O nome público da API a ser usado como parte da URL de serviço da API. Por padrão, este campo é preenchido com o nome da API 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:

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

  • Versão: Insira uma versão opcional para usar como parte da URL de serviço da API. Este campo permite um máximo de 48 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 usar uma data em que a API foi publicada, como 2021-08-28.

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

  • 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 de operação em Integration Studio ou Design Studio. As configurações de tempo limite de operação não são utilizadas a menos que um agente privado seja usado e a configuração EnableAPITimeout no arquivo de configuração do agente privado esteja habilitada.

  • Somente SSL: Quando selecionado (padrão), os dados são criptografados através de SSL e HTTPS é aplicado para todas as solicitações e respostas da API (recomendado).

    Quando não selecionado, os dados transmitidos através das solicitações e respostas da API não são criptografados e podem ser interceptados e visualizados por outros. Isso pode potencialmente expor informações sensíveis.

  • Habilitar CORS: Selecione para habilitar Compartilhamento de Recursos entre Origens (CORS) (não recomendado). Habilitar CORS está selecionado por padrão.

    Aviso

    Habilitar CORS faz com que operações usando o método OPTIONS sejam executadas sem autenticação.

  • Habilitar Registro Detalhado: Selecione para habilitar o registro detalhado. O registro detalhado para APIs inclui dados de solicitação e resposta em cada registro da 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 padrão é que o registro detalhado esteja desabilitado.

  • Habilitar Modo de Depuração Até: Selecione para habilitar o modo de depuração e permitir a entrada de uma data e hora correspondentes em que o modo de depuração será desabilitado. O comprimento máximo de habilitação é de duas semanas. O modo de depuração permite rastreamento completo para cada solicitação recebida através da URL de serviço da API. Quando habilitado, o sistema retém o conteúdo completo de cada solicitação e resposta da API por até 24 horas a partir do momento em que a chamada da API foi recebida e se aplica a todas as operações acionadas pela API.

    Nota

    Navegar pelos dados do evento pode se tornar difícil com grandes volumes (teste de carga, teste de pré-produção, etc.). O aumento nos dados retidos pode resultar em preocupações com espaço de armazenamento e segurança. Não recomendamos o uso do modo de depuração em um ambiente de produção.

  • Próximo: Clique para armazenar temporariamente a configuração para esta etapa e continuar para a próxima etapa.

  • Salvar Alterações: Clique para salvar a configuração para esta etapa e navegar para Etapa 4: Resumo e confirmação.

Etapa 2: Selecionar tipo de serviço e atribuir operações

selecionar tipo de serviço

  • Tipo de Serviço: Selecione API Personalizada.

  • Adicionar Serviço de API: Clique para adicionar um serviço de API para expor uma operação do Harmony para consumo. Uma vez clicado, a configuração do serviço de API individual é aberta (descrita abaixo). Vários serviços de API podem ser adicionados a uma API personalizada.

Após clicar em Adicionar Serviço de API, a configuração para um serviço de API é aberta:

publicar nova API etapa 2 atribuir operações personalizada

  • Método de solicitação: Use o menu para selecionar o método de solicitação para o serviço de API, um dos GET, POST, PUT, DELETE, ALL ou CUSTOM. Selecionar ALL criará métodos separados GET, PUT, POST e DELETE para a Operação selecionada (o método CUSTOM não está incluído). Por padrão, o método de solicitação é definido como GET.

    Nota

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

  • Nome do Serviço: Insira um nome para o serviço de API.

  • Caminho: Opcionalmente, insira um caminho para a solicitação. O caminho deve começar com uma barra / e deve ter todos os parâmetros de solicitação encerrados em chaves { }. Qualquer outro caractere especial não é permitido.

    Nota

    A combinação de método de solicitação e Caminho deve ser única para cada serviço de API na API personalizada.

  • Nome do Método Personalizado: Visível quando CUSTOM é selecionado como o método de solicitação. Insira o nome do método a ser utilizado, por exemplo, PATCH. (Apenas caracteres alfabéticos, hífens - e sublinhados _.)

  • Operação: Dentro da aba Operação, você seleciona um projeto e uma operação para atribuir ao serviço da API (necessário para habilitar o botão Salvar):

    • Atribuir Projeto: Use o menu para selecionar um projeto implantado do ambiente onde a API está sendo configurada (especificado em Passo 1: Configurações). Você pode digitar qualquer parte do nome do projeto no menu para filtrar a lista de projetos. Os resultados do menu são filtrados em tempo real a cada tecla pressionada.

    • Editar Projeto: Quando um projeto do Integration Studio é selecionado, este botão é habilitado. Clicar em Editar Projeto abre o projeto no Integration Studio em uma nova aba.

      Nota

      Você deve implantar quaisquer alterações feitas no projeto para que elas tenham efeito.

    • Atribuir Operação(ões): Use os menus para selecionar uma Operação e um Tipo de Resposta para o serviço da API:

      • Operação: Selecione entre as operações implantadas no projeto selecionado. Você pode digitar qualquer parte do nome da operação no menu para filtrar a lista de operações implantadas. Os resultados do menu são filtrados em tempo real a cada tecla pressionada.

        Importante

        Por padrão, operações bem-sucedidas configuradas para uma API personalizada não estão incluídas nos logs de operação a menos que uma dessas configurações esteja habilitada:

        Operações malsucedidas estão incluídas nos logs de operação independentemente de as configurações acima estarem habilitadas ou não.

      • Tipo de Resposta: Selecione entre Destino Final, Variável do Sistema ou Sem Resposta:

        • Destino Final: A resposta da API é o destino final da cadeia de operações. Quando este tipo de resposta é selecionado, a operação selecionada deve ter, como destino final da cadeia de operações, uma atividade de Resposta da API do Integration Studio ou uma atividade de Gravação de Variável, ou um destino de Resposta da API do Design Studio ou um destino de Variável Global. 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 cadeia de operações. Quando este tipo de resposta é selecionado, a operação selecionada deve ter, como parte da 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 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.

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

    aba de parâmetros de caminho

    • 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.

  • Parâmetros de consulta: Esta aba permite adicionar quaisquer parâmetros de consulta ao serviço da API:

    aba de parâmetros de consulta

    • Adicionar Parâmetro: Clique para adicionar um parâmetro de consulta ao serviço da API. Uma vez 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 excluir ao lado de um parâmetro de consulta para deletar esse parâmetro.

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

    aba de cabeçalhos

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

      • Excluir: Clique no ícone de excluir ao lado de um cabeçalho de solicitação para deletar esse cabeçalho.

  • Duplicar: Clique no ícone de duplicar para criar uma duplicata do serviço da API.

    Nota

    Uma vez que o serviço da API é duplicado, você deve alterar ou o método de solicitação ou o Caminho, pois cada serviço da API deve ter uma combinação única desses campos.

  • Excluir: Clique no ícone de excluir ao lado de um serviço da API para deletá-lo da API personalizada.

  • Salvar: Clique para salvar o serviço da API. Quando a configuração para todos os serviços da API estiver completa, os botões Próximo e Salvar Alterações são habilitados. Uma configuração de serviço da API incompleta é indicada com um ícone de erro ao lado do nome do serviço da API:

    serviço da API incompleto

Para resolver e habilitar os botões Próximo e Salvar Alterações, complete a configuração ou exclua o serviço da API.

  • Cancelar: Clique para cancelar a configuração do serviço da API.

  • Próximo: Clique para armazenar temporariamente a configuração para esta etapa e continuar para a próxima etapa.

  • Salvar Alterações: Clique para salvar a configuração para esta etapa e navegar para Etapa 4: Resumo e confirmação.

Etapa 3: Atribuir funções de usuário e perfis de segurança

publicar nova API etapa 3 funções de usuário perfis de segurança

  • Atribuir Funções de Usuário: Selecione os papéis da organização cujos membros terão acesso à API a partir das páginas do Gerenciador de API listadas abaixo. Os papéis disponíveis são aqueles definidos na aba Papéis da página de Gerenciamento de Usuários.

    Isso determina o acesso a esta API específica a partir dessas páginas:

    O acesso à página de Perfis de Segurança e o acesso para consumir a API não são afetados por esta seleção. (O acesso para consumir uma API é controlado por perfis de segurança.)

    Quaisquer papéis de usuário definidos com a permissão Admin sempre têm acesso total a todas as APIs e, portanto, não podem ser desmarcados. (No exemplo da captura de tela mostrada acima, o papel Administrador não pode ser desmarcado por esse motivo.)

    Nota

    APIs criadas antes do Harmony 10.22 têm todos os papéis de usuário selecionados por padrão para garantir o acesso contínuo a todos os usuários.

  • Atribuir Perfil(is) de Segurança: Use o menu suspenso para selecionar um perfil de segurança existente que será utilizado para restringir o acesso ao consumo da API. Você pode digitar qualquer parte do nome do perfil de segurança no menu para filtrar a lista de perfis de segurança. Os resultados do menu são filtrados em tempo real a cada tecla pressionada. Um perfil de segurança pode ser necessário para ser atribuído a fim de salvar a API, dependendo das políticas da organização Harmony.

    • Atribuir Perfil: Clique para atribuir um perfil de segurança selecionado à API. Os perfis de segurança atribuídos são listados na tabela com o Nome do Perfil e Tipo conforme configurado para o perfil de segurança na configuração do perfil de segurança. Se o Tipo for Básico, a coluna Nome de Usuário exibe o Nome de Usuário fornecido durante a configuração. Se o Tipo for qualquer outro tipo, a coluna Nome de Usuário exibe o mesmo valor que o Tipo. Para remover um perfil atribuído, clique no ícone de remover.
    • Criar Novo Perfil: Clique para criar um novo perfil de segurança. Para instruções, veja Perfis de Segurança.

  • Próximo: Clique para armazenar temporariamente a configuração para esta etapa e continuar para a próxima etapa. Se a API não tiver um perfil de segurança necessário atribuído, esta opção estará desabilitada.

  • Salvar Alterações: Se habilitado, clique para salvar a configuração para esta etapa. Se a API não tiver um perfil de segurança necessário atribuído, esta opção estará desabilitada.

  • Pular esta Etapa: Se presente, clique para continuar para a próxima etapa sem armazenar a configuração para esta etapa. Se a API não tiver um perfil de segurança necessário atribuído, esta opção não estará presente.

Etapa 4: Resumo e confirmação

publicar nova API etapa 4 resumo

  • Nome da API e Ambiente: O nome da API seguido pelo ambiente entre parênteses, conforme configurado em Passo 1: Configurações.

    • Descrição, Tempo limite, Apenas SSL, CORS Habilitado e Registro detalhado habilitado: A descrição da API e outras configurações que estão habilitadas () ou desabilitadas (). Para fazer alterações nessas configurações, clique no ícone de edição para retornar a Passo 1: Configurações.
    • Habilitar Modo de Depuração Até: Esta opção é a mesma que a descrita em Passo 1: Configurações. Você pode alterar esta configuração diretamente a partir deste passo, em vez de ser necessário retornar ao primeiro passo.

  • Operações: As operações atribuídas em Passo 2: Selecionar tipo de serviço e atribuir operações com as informações correspondentes para o tipo de serviço selecionado. Para fazer alterações, clique no ícone de edição para retornar a Passo 2: Selecionar tipo de serviço e atribuir operações.

  • Funções de Usuário e Perfis de Segurança: As funções e perfis de segurança atribuídos em Passo 3: Atribuir funções de usuário e perfis de segurança. Para fazer alterações, clique no ícone de edição para retornar a Passo 3: Atribuir funções de usuário e perfis de segurança.

  • Exportar: Gera e inicia o download de um arquivo APK (apis-export.apk) contendo uma exportação da API (veja Exportando e importando APIs).

  • Clonar: Cria uma cópia de uma API existente. Na cópia da API, o Nome da API é precedido por Cópia de, a Raiz do Serviço é precedida por Copia de, e a Versão é acrescida de -2. A cópia da API é imediatamente aberta em seu próprio Passo 4: Resumo e confirmação.

  • Excluir: Exclui permanentemente a API e fecha a configuração. Um diálogo solicita que você confirme que deseja excluir a API.

    Nota

    Se o status da API era Publicado ou Publicado com Rascunho no momento da exclusão, ele também é removido do número de URLs de API usadas contra o limite da sua assinatura. Se o status da API era Rascunho no momento da exclusão, o número de URLs de API usadas contra o limite da sua assinatura não muda, pois a API não estava acessível enquanto estava em status de Rascunho.

  • Salvar como Rascunho: Salva a API no status Rascunho ou Publicado com Rascunho:

  • Rascunho: Uma nova API ou uma API cujo status era Rascunho no momento em que Salvar como Rascunho foi utilizado. Rascunhos não contam contra o seu limite de assinatura de URLs de API.

  • Publicado com Rascunho: Uma API cujo status era Publicado no momento em que Salvar como Rascunho foi utilizado. Uma API que é publicada com um rascunho conta contra o seu limite de assinatura de URLs de API, pois a API é acessível, embora seu rascunho não seja.

  • Salvar e Publicar: Salva a API no status Publicado. A API está ao vivo e acessível em cinco minutos. Uma API publicada conta contra o seu limite de assinatura de URLs de API, pois a API é acessível. Um diálogo indica que a API está ao vivo:

    tudo pronto sua API está ao vivo API personalizada

  • Copiar URL: Copia a URL de serviço da API (veja URL de serviço da API).

  • Gerar Documento OpenAPI: Abre a página Portal Manager, onde você pode gerar documentação da API para a página Portal.
  • Dispensar: Fecha o diálogo.

Editar a API

Após salvar a API, você pode editá-la a partir destes locais: