Página de APIs no Jitterbit API Manager

Introdução

A página de APIs é a página principal do API Manager. Ela permite que os administradores da organização Harmony gerenciem três tipos de APIs:

• APIs Personalizadas
• Serviços OData
• APIs Proxy

Membros de um papel que recebeu Acesso de Leitura ao ambiente podem visualizar apenas as APIs nesse ambiente. Membros de um papel que recebeu Acesso de Escrita ao ambiente têm acesso de escrita nesse ambiente.

Para acessar a página de APIs, use o menu do portal Harmony para selecionar API Manager > APIs.

Cabeçalho da página de APIs

O cabeçalho na parte superior da página de APIs inclui estes controles:

• URL base da API: A URL base da API da organização Harmony. Clique no ícone Copiar para copiar a URL para sua área de transferência. (Você verá uma confirmação da ação.)

• URLs de API Personalizadas usadas: O número de URLs de API personalizadas atualmente usadas em relação ao número total de URLs de API personalizadas permitidas pela assinatura da organização. As URLs de API atualmente usadas incluem aquelas utilizadas por APIs Personalizadas publicadas e Serviços OData e seus clones publicados. APIs em rascunho não contam como URLs de API em uso.

• URLs de API Proxy usadas: O número de URLs de API proxy atualmente usadas em relação ao número total de URLs de API proxy permitidas pela assinatura da organização. As URLs de API proxy atualmente usadas incluem aquelas utilizadas por APIs Proxy publicadas e seus clones publicados. APIs em rascunho não contam como URLs de API em uso.

• Filtro: Abre um painel com controles para filtrar a tabela por Tipo de API, Status da API, Grupo de API, Ambiente, Perfil de Segurança, e datas de Última Edição e Última Publicação:

  

  Os filtros são aplicados imediatamente. Use os botões Limpar ou Limpar Tudo para redefinir os filtros, e o botão Fechar para fechar o painel.

• Pesquisar: Digite qualquer parte do nome da API, versão, ambiente, tipo, descrição, status, ou a data ou hora em que a API foi publicada ou editada pela última vez na caixa de pesquisa para filtrar a lista de APIs. Use apenas caracteres alfanuméricos. A pesquisa não diferencia maiúsculas de minúsculas.

• Visualizar: Clique no ícone visualização em blocos ou visualização em lista para alternar o formato usado para exibir APIs nesta página. A visualização em blocos é a visualização padrão inicial. Na próxima vez que você carregar a página APIs, a última visualização selecionada será pré-selecionada.

• Importar API: Abre a tela de importação de API, onde você pode importar APIs no formato APK (veja Exportando e importando APIs).

• Exportar API: Abre a tela de exportação de API, onde você pode exportar APIs selecionadas no formato APK (veja Exportando e importando APIs).

• Novo: Use o menu para selecionar o tipo de API a ser criada, seja API Personalizada ou API Proxy:

  • API Personalizada: (Disponível apenas se uma URL de API personalizada estiver disponível.) Abre a tela de configuração da API para criar uma nova personalizada ou OData API.

  • API Proxy: (Disponível apenas se uma URL de API proxy estiver disponível.) Abre a tela de configuração da API proxy para criar uma nova proxy API.

Visualização em bloco

Para acessar a visualização em bloco, selecione o ícone Visualização em bloco .

A visualização em bloco exibe APIs como blocos. Cada bloco tem uma frente e um verso que podem ser "virados" para revelar informações e ações adicionais da API. A frente é exibida por padrão. O verso é exibido quando você passa o mouse sobre o bloco:

• Frente: A frente do bloco mostra o nome da API, versão, ambiente, tipo de API (Personalizada, OData ou Proxy), status da API (Publicado, Publicado com Rascunho ou Rascunho), e a data da última edição ou da última publicação (no formato MM/DD/YY) no horário local do navegador. A cor do ícone à esquerda do status da API indica a categoria do status da API:

  Ícone	Cor	Categoria
  	Verde	A API está publicada.
  	Amarelo	A API está publicada com um rascunho.
  	Verde Aberto	A API é um rascunho.

• Verso: O verso do bloco (visível ao passar o mouse sobre um bloco) mostra o nome da API, ambiente, descrição da API e nome do usuário que editou a API por último. Além disso, estas ações estão disponíveis:

  • Visualizar/Editar: Abre a tela de configuração da API (veja Configuração de API Personalizada, Configuração de serviço OData ou Configuração de API Proxy).

  • Ações: Clique no ícone do menu de ações para abrir um menu com estas ações:

    Item do menu da API	Descrição
    	Logs da API abre a página Logs da API, que exibe logs de processamento e depuração (se o registro de depuração estiver habilitado) para todas as APIs.
    	Análise abre a página Análise, que exibe métricas de consumo e desempenho para todas as APIs.
    	Clonar abre a tela de configuração da API (veja Configuração de API personalizada, Configuração de serviço OData ou Configuração de API Proxy), pré-preenchida com os detalhes de configuração da API clonada e valores padrão atualizados para estes campos: Nome da API: O nome da API é precedido por Cópia de. Raiz do Serviço: A raiz do serviço é precedida por Cópia de. Versão: A versão é acrescida de -2. Este número não é incrementado com clones adicionais.
    	Exportar inicia o download da API para um arquivo chamado apis-export.apk. Este arquivo pode ser importado em um ambiente ou organização diferente (veja Exportando e importando APIs).
    	Excluir exclui permanentemente a API. Ao clicar em Excluir, um diálogo de confirmação é exibido para confirmar que você deseja excluir permanentemente a API. Cuidado A documentação OpenAPI exibida na página Portal não é atualizada automaticamente quando você exclui uma API. Para atualizar a documentação OpenAPI, faça isso através da página Portal Manager.

• Copiar URL: Copia a URL da API para sua área de transferência. Nenhuma mensagem de confirmação aparece.

Visualização em lista

Para acessar a visualização em lista, selecione o ícone Visualização em lista .

A visualização em lista exibe as APIs em uma tabela. Cada coluna é descrita abaixo. Clicar em uma linha de API abre a gaveta de detalhes da API.

As colunas disponíveis são as seguintes:

• Nome da API: O nome da API.

• Versão: A versão da API, conforme inserido durante a configuração da API.

• Tipo: O tipo de API, um de API Personalizada, Serviço OData ou API Proxy.

• Ambiente: O ambiente onde a API está armazenada.

• Status: O status da API, um de Publicado, Publicado com rascunho, ou Rascunho.

• Última Edição: A data da última salvamento (no formato MM/DD/YYYY), hora (no formato HH:MM:SS), e o período de tempo (AM ou PM) no horário local do navegador.

• Raiz do serviço: O nome público da API, conforme inserido durante a configuração da API.

• Grupo: O nome de quaisquer grupos de API aos quais a API pertence.

• Editado Por: O nome do usuário que salvou a API por último.

• Última Publicação: A data de publicação (no formato MM/DD/YYYY), hora (no formato HH:MM:SS), e o período de tempo (AM ou PM) no horário local do navegador.

• Publicado Por: O nome do usuário que publicou a API por último.

• Gateway: O gateway da API utilizado pela API.

• Serviços: O número de serviços configurados para a API.

• Ações: Passe o mouse sobre a linha da API para revelar ações adicionais:

  • Detalhes: Abre a gaveta de detalhes da API (descrita na próxima seção).

  • Copiar URL base da API: Clique para copiar a URL base da API para sua área de transferência. Uma mensagem de confirmação aparece quando a ação é concluída.

  • Exportar: Abre o seletor de pastas para sua máquina local. Selecione uma pasta para salvar a exportação da API. Para mais informações, veja Exportar e importar APIs.

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

  • Mais ações: Abre um menu com estas ações:

    Item do menu da API	Descrição
    Clonar	Abre a tela de configuração da API (veja Configuração de API personalizada, Configuração de serviço OData ou Configuração de API Proxy), pré-preenchida com os detalhes de configuração da API clonada e padrões atualizados para estes campos: Nome da API: O nome da API é precedido por Cópia de. Raiz do Serviço: A raiz do serviço é precedida por Cópia de. Versão: A versão é acrescida de -2. Este número não aumenta com clones adicionais.
    Excluir	Exclui permanentemente a API. Ao clicar em Excluir, um diálogo de confirmação é exibido para confirmar que você deseja excluir permanentemente a API. Cuidado A documentação OpenAPI exibida na página Portal não é atualizada automaticamente quando você exclui uma API. Para atualizar a documentação OpenAPI, faça isso através da página Portal Manager.
    Ver no portal	(Habilitado apenas para APIs personalizadas ou proxy com status Publicado ou Publicado com Rascunho.) Abre a página Portal para a API.
    Ver logs	Abre a página Logs da API, que exibe logs de processamento e depuração (se o registro de depuração estiver habilitado) para todas as APIs.
    Análises	Abre a página Análises, que exibe métricas de consumo e desempenho para todas as APIs.

API details drawer

Enquanto estiver na visualização de lista, selecione uma API na tabela ou clique em Editar para visualizar e editar os detalhes de uma API. Um painel se abre na parte inferior da janela com estas abas dependendo do tipo de API:

O cabeçalho do painel exibe estes detalhes e controles:

• Nome e versão da API: Exibe o nome da API e sua versão, se aplicável.

• Anterior / Próximo: Navega pela lista de APIs da organização.

• Expandir: Expande o painel para tela cheia. Uma vez expandido, clique no ícone Minimizar para retornar à visualização anterior.

• Fechar: Fecha o painel.

• Descartar alterações: Após fazer alterações, clique para fechar o painel sem salvar as alterações feitas em qualquer etapa. Uma mensagem pede para confirmar que você deseja descartar as alterações.

• Salvar como rascunho: Salva quaisquer alterações na API no status Rascunho ou Publicado com Rascunho:

  • Rascunho: Uma nova API ou uma API cujo status era Rascunho quando Salvar como Rascunho foi utilizado. Rascunhos não contam contra o limite da sua assinatura.

  • Publicado com Rascunho: Uma API cujo status era Publicado quando Salvar como Rascunho foi utilizado. Uma API que é publicada com um rascunho conta contra o limite da sua assinatura porque a API é acessível, mesmo que seu rascunho não esteja.

• Publicar: Salva as alterações na API com status Publicado. A API está ativa e acessível em cinco minutos. Uma API publicada conta contra o limite da sua assinatura porque a API é acessível. Um diálogo indica que a API está ativa. Clique em Copiar URL para copiar a URL do serviço da API.

Aba Perfil

A aba Perfil exibe informações gerais sobre a API:

• Tipo de API: O tipo de API, que pode ser API Personalizada, Serviço OData ou API Proxy.

• URL Base da API: A URL base da API.

• Nome da API: O nome da API para fins de identificação interna. Os seguintes caracteres especiais são permitidos: ( ) - _

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

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

• Descrição: (Visível apenas para APIs personalizadas e serviços OData.) A descrição da API.

• Ambiente: O ambiente onde a API reside. Este campo não pode ser editado.

• Número da Versão: A versão usada como parte da URL do 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 o incremento de versões, como v1.0, v1.1, v1.2, ou o uso de uma data em que a API foi publicada, como 2021-08-28.

Aba Configurações

Na aba Configurações, você pode visualizar ou editar as configurações de uma API:

• Timeout: 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 em Integration Studio ou Design Studio. As configurações de tempo limite da 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.

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

  Quando desabilitado, 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.

• CORS: Quando habilitado, o mecanismo de Cross-Origin Resource Sharing (CORS) é utilizado (não recomendado).

  Aviso

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

• Verbose logging: Quando habilitado, o registro detalhado para APIs inclui dados de solicitação e resposta em cada registro da API para ajudar a monitorar os dados de entrada e saída e facilitar a depuração. Esta configuração está desabilitada por padrão, pois pode criar arquivos de log grandes.

• Enable debug mode until: Exibe a data e hora em que o modo de depuração será desabilitado.

Existing API tab

Na aba Existing API você pode visualizar e editar a URL base de uma API proxy:

• Base API URL: A URL base da API a ser proxy.

  Nota

  Se a API fornecer um único serviço, você pode inserir a URL completa da API, incluindo o caminho do serviço.

• Fornecer documento OpenAPI: Quando um documento OpenAPI é fornecido, ele é usado para descobrir automaticamente os serviços da API. Selecione Não para pular ou Sim para expandir uma área adicional para fornecer o documento OpenAPI:

  

  • URL OpenAPI: Quando selecionado, um campo URL OpenAPI fica disponível para você inserir uma URL. Clique em Aplicar para carregar um documento OpenAPI no formato YAML ou JSON a partir da URL.

  • Enviar arquivo: Quando selecionado, faz o upload de um documento OpenAPI no formato YAML ou JSON após usar Procurar para selecionar o arquivo:

    

  • Editor de documentos: Permite visualizar e editar um documento OpenAPI fornecido. Você também pode fornecer um documento OpenAPI inserindo-o diretamente aqui. Para visualizar e editar o documento OpenAPI em uma área maior, clique no ícone de expansão (após abrir essa área, clique no ícone de retorno para voltar a esta tela).

Aba Serviços

Na aba Serviços, você pode adicionar novos serviços ou visualizar e editar os serviços da API atuais. Clique em um serviço da API para editá-lo.

Você pode classificar a tabela por Nome do Serviço, Método, Caminho, Projeto, Operação a Acionar ou Tipo de Resposta clicando na respectiva linha de cabeçalho.

• Pesquisar: Insira qualquer parte do nome do serviço, método, caminho, projeto, operação ou tipo de resposta 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 Serviço: Adiciona uma linha de serviço da API ao final da tabela. Insira ou selecione valores para cada campo na tabela (descrito abaixo).

• Nome do Serviço: O nome do serviço da API.

• Método: O método de solicitação para o serviço da API, um dos GET, POST, PUT, DELETE, ALL, ou (se o Método estiver definido como CUSTOM) o nome do método personalizado.

• Caminho: O caminho para a solicitação.

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

• Operação a Acionar: (Visível apenas para APIs personalizadas e serviços OData.) O nome da operação que está sendo chamada.

• Tipo de Resposta: (Visível apenas para APIs personalizadas e serviços OData.) O tipo de resposta, um dos Final Target, System Variable, ou No Response.

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

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

  • Ir para o Serviço da 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 serviços OData.) Cria uma duplicata do serviço da API. Você deve alterar o método de solicitação ou o Caminho, pois cada serviço da API deve ter uma combinação única desses campos.

  • Excluir: Exclui o serviço da API.

  Quando você clica em uma linha de serviço de 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 da 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 excluir ao lado de um parâmetro de consulta para deletar 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 do serviço da API.

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

Aba de Perfis de Segurança

A aba Perfis de Segurança fornece uma lista de perfis de segurança disponíveis no ambiente:

Você pode classificar a tabela por Nome do Perfil, Tipo ou Nome de Usuário clicando na respectiva linha do cabeçalho.

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

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

  Nota

  Você pode atribuir múltiplos perfis de segurança com o mesmo tipo de autenticação à API. Apenas os tipos de autenticação básica e chave de API podem ser usados juntos.

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

• Tipo: O tipo de autenticação, um dos 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 utilizem 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.

Aba de papéis de usuário

A aba Papéis de Usuário fornece uma lista dos papéis da organização cujos membros têm acesso à API:

Você pode classificar a tabela por Papel de Usuário clicando na respectiva linha do cabeçalho.

• Pesquisar: Digite qualquer parte do papel 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.

• Novo papel de usuário: Abre um painel para configurar um novo papel de usuário:

  

  • Nome do papel: Digite um nome único para o papel.

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

    

    Note

    A permissão Desenvolvedor de Aplicativos está obsoleta e não é mais utilizada.

  • Status: Exibe se o papel de usuário está atribuído ou não atribuído à API.

    Regras de gerenciamento de papéis

    Essas regras se aplicam ao gerenciamento de papéis em APIs:

    • Usuários com Admin permissão ou Acesso de Escrita acesso ao ambiente podem atribuir ou desatribuir papéis às APIs.
    • Usuários com Admin permissão podem criar e atribuir novos papéis.
    • 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.

• Função do Usuário: O nome da função do usuário do Harmony.

• 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 da Console de Gerenciamento.

Aba de cabeçalhos de solicitação

A aba Cabeçalhos de Solicitação fornece uma lista dos cabeçalhos de solicitação de uma API proxy:

Você pode classificar a tabela por Chave ou Valor clicando na respectiva linha do cabeçalho.

• Chave: A chave do cabeçalho de solicitação.

• Valor: O valor do cabeçalho de solicitação.

• Substituir Entrada: Quando ativado, o cabeçalho de solicitação substitui outros cabeçalhos de solicitação que usam a mesma Chave.

  Nota

  Para editar esta configuração, você deve clicar em Editar na coluna Ação da API na tabela.

• Ações: Passe o mouse sobre a linha do cabeçalho de solicitação para revelar uma ação adicional:

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

Configurações da página de visualização em lista

Você pode classificar a tabela, reorganizar suas colunas ou atualizar seu conteúdo:

• Classificar: Para classificar a tabela em ordem crescente, clique em qualquer cabeçalho de coluna. Clique novamente para inverter a ordem de classificação.

• Colunas: Para alterar a disposição e a visibilidade das colunas, clique em Filtrar colunas. O painel Colunas se abre:

  

  O painel possui os seguintes controles:

  • Pesquisar: Digite qualquer parte do nome da coluna na caixa de pesquisa para filtrar a lista de colunas. Use apenas caracteres alfanuméricos. A pesquisa não diferencia maiúsculas de minúsculas.

  • Mostrar Todas: Torna todas as colunas visíveis.

  • Mover: Arraste e solte para alterar a posição da coluna em relação às outras.

  • Ocultar: A coluna está visível. Clique para ocultá-la.

  • Mostrar: A coluna está oculta. Clique para mostrá-la.

  • Salvar: Salvar as colunas.

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