Ir para o conteúdo

Configuração de API Customizada

Introdução

Esta página descreve como criar e configurar uma API Customizada em Minhas APIs página do Jitterbit Harmony API Manager. APIs personalizadas são um dos três tipos de APIs configurado por meio do API Manager. Para os outros dois tipos — Serviço OData e proxy de API — consulte Configuração do Serviço OData e Configuração da proxy de API.

Como alternativa, APIs personalizadas podem ser criadas no Cloud Studio usando Publicar como API opção acessada a partir de um menu de ação da operação.

Nota

Depois de publicada, cada API Customizada conta como um URL da API em relação ao seu limite de assinatura do Jitterbit Harmony.

Pré-requisitos

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

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

Criando uma Nova API Customizada

Ao acessar o API Manager Minhas APIs, se não existirem APIs personalizadas, serviços OData ou APIs de proxy na organização selecionada, esta tela ficará em branco.

Para criar uma nova API Customizada, clique em Nova API:

sem APIs nova API

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

Configurando uma API Customizada

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

O URL de serviço de uma API é o URL usado para consumir a API usando um método de autenticação configurado. As partes do URL de serviço de uma API são descritas em Introdução ao API Manager em URL do serviço API.

O URL do serviço é exibido na parte superior de cada etapa:

publicar novo URL do serviço de configurações da etapa 1 da API

Etapa 1: Configurações

publicar novas configurações da etapa 1 da API

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

  • Ambiente: O ambiente onde a API reside.

    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: A nome público da API a ser usada como parte do 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 determinados caracteres especiais. Usando caracteres especiais diferentes de sublinhado (_) não é recomendado. Estes caracteres especiais são permitidos:

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

  • Versão: Insira uma versão opcional para usar como parte do URL de serviço da API. Este campo permite no máximo 48 caracteres e não permite espaços ou determinados caracteres especiais. Usando caracteres especiais diferentes de ponto final (.) ou um hífen (-) não é recomendado. As convenções de nomenclatura comuns incluem versões incrementais, como v1.0, v1.1, v1.2ou usando 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 expire. 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 Cloud Studio ou Design Studio. As configurações de tempo limite de operação não são usadas a menos que um Agente Privado é usado e o EnableAPITimeout configuração no arquivo de configuração do Agente Privado está ativado.

  • Somente SSL: Selecione exigir o uso de criptografia SSL (recomendado). Somente SSL é selecionado por padrão.

  • Ativar CORS: Selecione para ativar Compartilhamento de recursos entre origens (CORS) (não recomendado). Ativar CORS é selecionado por padrão.

    Aviso

    Habilitar o CORS faz com que operações usando o OPTIONS método para ser executado sem autenticação.

  • Ativar registro detalhado: Selecione para ativar o registro detalhado. O registro detalhado para APIs inclui 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 padrão é que o log detalhado esteja desabilitado.

  • Ativar modo de depuração até: Selecione para ativar o modo de depurar e ativar a inserção de uma data e hora correspondentes nas quais o modo de depurar será desativado. A duração máxima da habilitação é de duas semanas. O modo de depuração permite o rastreamento completo de cada solicitação recebida por meio do URL de serviço da API. Quando ativado, 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

    A passagem pelos dados do evento pode se tornar difícil com grandes volumes (testes de carga, testes de pré-produção, etc.). O aumento nos dados retidos pode resultar em problemas de espaço de armazenamento e segurança. Não recomendamos usar o modo de depurar em um ambiente de produção.

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

  • Salvar alterações: Clique para salvar a configuração desta etapa e navegar até Etapa 4: Resumo e confirmação.

Etapa 2: Selecione o Tipo de Serviço e Atribua Operações

publicar nova etapa 2 da API atribuir operações personalizadas

  • Tipo de serviço: Selecione API Customizada.

  • Atribuir projeto: Use o menu para selecionar um projeto implantado no ambiente onde a API está sendo configurada (especificado em Etapa 1: Configurações).

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

    Nota

    Você deve implantar quaisquer alterações feitas no projeto para que elas entrem em vigor.

  • Atribuir operação(ões): Use os menus para selecionar uma Operação, Método e Tipo de resposta para a API Customizada:

    • Operação: Selecione uma das operações implantadas no projeto selecionado.

      Importante

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

      As operações malsucedidas são incluídas nos logs de operação estejam as configurações acima habilitadas ou não.

    • Método: Selecione o método de solicitação a ser usado para a operação selecionada, um de GET, PUT, POST, DELETE, TODOS ou PERSONALIZADO. Selecionar TODOS criará GET, PUT, POST, e DELETE métodos para a Operação selecionada. Somente uma operação usando cada método pode ser atribuída.

    - Tipo de resposta: Selecione entre Alvo final, Variável do sistema ou Sem resposta:

    - **Alvo Final:** A resposta da API é o alvo final da cadeia de operação. Quando este tipo de resposta é selecionado, a operação selecionada deve ter, como destino final da cadeia de operação, uma [atividade de resposta de API  do Cloud Studio](/pt/cloud-studio/cloud-studio-reference/connectors/api/request-activity) ou [Atividade de gravação de variável](/pt/cloud-studio/cloud-studio-reference/connectors/variable/variable-write-activity/) ou um destino de resposta da API do Design Studio ou [alvo de variável global](/pt/design-studio/design-studio-reference/sources-and-targets/global-variable/global-variable-target/). Se qualquer outro destino final for usado, a resposta da API estará vazia.

- **Variável de Sistema:** A resposta da API é definida em uma variável Jitterbit na cadeia de operação. Quando este tipo de resposta é selecionado, a operação selecionada deve ter, como parte da cadeia de operação, um script que configure 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 o código HTTP 202.

  • Atribuir operação: Depois que uma Operação, Método e Tipo de resposta forem selecionados, clique em Atribuir operação para adicionar a operação à API Customizada. Pelo menos uma operação deve ser adicionada para ativar o botão Próximo.

    Nota

    Após clicar em Atribuir Operação, você não poderá mais alterar o Tipo de Serviço.

  • Operações atribuídas: Uma tabela exibe todas as operações que foram atribuídas à API Customizada. Para remover uma operação atribuída, clique no ícone de remoção anexo.

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

  • Salvar alterações: Clique para salvar a configuração desta etapa e navegar até Etapa 4: Resumo e confirmação.

Etapa 3: Atribuir Funções de Usuário e Perfis de Segurança

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

  • Atribuir funções de usuário: Selecione as funções da organização cujos membros terão acesso à API nas páginas do API Manager listadas abaixo. As funções disponíveis são aquelas definidas na página Organizações do Management Console (consulte Gerenciamento de funções e permissões em Organizações).

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

    Acesso aos 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 funções de usuário definidas com a permissão Admin sempre têm acesso total a todas as APIs e, portanto, não podem ser apagadas da seleção. (Na captura de tela de exemplo mostrada acima, as funções Administrador e Operações não podem ser apagadas por esse motivo.)

    Nota

    APIs criadas antes do Harmony 10.22 têm todas as funções de usuário selecionadas por padrão para garantir acesso contínuo para todos os usuários.

  • Atribuir perfil(es) de segurança: Use o menu suspenso para selecionar um perfil de segurança existente que será usado para restringir o acesso para consumo da API. Pode ser necessário atribuir um perfil de segurança para 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 Nome do perfil e Tipo conforme configurado para o perfil de segurança em Configuração do perfil de segurança. Se Tipo for Básico, a coluna Nome de usuário exibirá o Nome de usuário fornecido durante a configuração. Se Type for qualquer outro tipo, a coluna Username exibirá o mesmo valor que Type. Para remover um perfil atribuído, clique no ícone de remoção anexo.
    • Criar novo perfil: Clique para criar um novo perfil de segurança. Para obter instruções, consulte Configuração do perfil de segurança.

  • Próximo: Clique para armazenar temporariamente a configuração desta etapa e continuar para a próxima etapa. Se a API não receber um perfil de segurança obrigatório, esta opção será desativada.

  • Salvar alterações: Se ativado, clique para salvar a configuração desta etapa. Se a API não receber um perfil de segurança obrigatório, esta opção será desativada.

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

Etapa 4: Resumo e Confirmação

publicar novo resumo da etapa 4 da API

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

    • Descrição, Tempo limite, Somente SSL, CORS ativado e Log detalhado ativado: A descrição da API e outras configurações que estão ativadas ( verifique 2) ou desabilitado (check 2). Para fazer alterações nessas configurações, clique no ícone de edição check 2 para retornar à Etapa 1: Configurações.
    • Ativar modo de depuração até: Esta opção é a mesma descrita em Etapa 1: Configurações. Você pode alterar essa configuração diretamente nesta etapa, em vez de precisar retornar à primeira etapa.

  • Operações: As operações atribuídas na Etapa 2: Selecionar tipo de serviço e atribuir operações com as informações correspondentes ao tipo de serviço selecionado. Para fazer alterações, clique no ícone de edição anexo para retornar à Etapa 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 na Etapa 3: Atribuir funções de usuário e perfis de segurança. Para fazer alterações, clique no ícone de edição anexo para retornar à Etapa 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 (consulte Exportando e importando APIs).

  • Clone: Cria uma cópia de uma API existente. Na cópia da API, Nome da API é prefixado com Copy of, Service Root é prefixado com Copyof e Version é anexado com -2. A cópia da API é imediatamente aberta Etapa 4: Resumo e confirmação.

  • Excluir: Exclui permanentemente a API e fecha a configuração. Uma caixa de diálogo solicitará 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 será removido do número de URLs de API usados em seu limite de assinatura. Se o status da API era Rascunho no momento da exclusão, o número de URLs de API usados em relação ao seu limite de assinatura não muda, pois a API não estava acessível enquanto estava no status Rascunho.

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

  • Rascunho: Uma nova API ou uma API cujo status era Rascunho no momento em que Salvar como rascunho foi usado. Os rascunhos não contam para o seu limite de assinatura de API URL.

  • Publicado com rascunho: Uma API cujo status era Publicado no momento em que Salvar como rascunho é usada. Uma API publicada com um rascunho conta para seu limite de assinatura de API URL, pois a API é acessível, mas seu rascunho não.

  • Salvar e publicar: Salva a API no status Publicado. A API está ativa e acessível em cinco minutos. Uma API publicada é contabilizada em seu limite de assinatura de API URL, pois a API está acessível. Uma caixa de diálogo indica que a API está ativa:

    tudo configurado, sua API é uma API personalizada ao vivo

  • Copiar URL: Copia o URL do serviço da API (consulte URL do serviço API).

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