Configuração do serviço OData no Jitterbit API Manager

Introdução

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

Pré-requisitos

Como um serviço OData expõe uma operação de entidade de API do Jitterbit iPaaS para consumo, tal operação deve primeiro ser criada e implantada. A operação que um serviço OData aciona deve ser uma operação de entidade de API do Design Studio. A operação de entidade de API existente é então referenciada durante a configuração do serviço OData. Nesta página, a palavra API é usada para se referir a um serviço OData.

Para informações sobre como criar e implantar uma operação de entidade de API no Design Studio, consulte estes recursos:

• Guia de início rápido do Design Studio
• Criar uma entidade Jitterbit
• Criar uma operação de entidade de API

Criar um novo serviço OData

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

Para criar um novo serviço OData, clique em Novo > API Personalizada:

Ao clicar em API Personalizada, a tela de configuração da API é aberta. Detalhes sobre como configurar um novo serviço OData são fornecidos em Configurar um serviço OData abaixo.

Configurar um serviço OData

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

• Etapa 1: Configurações
• Etapa 2: Selecionar tipo de serviço e atribuir operações
• Etapa 3: Atribuir funções de usuário e perfis de segurança
• Etapa 4: Resumo e confirmação

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 URL do serviço da API.

A URL do Serviço é exibida na parte superior de cada etapa:

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

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

• 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 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 o uso de 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 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.

• Somente SSL: Quando selecionado (padrão), os dados são criptografados através de SSL e HTTPS é imposto 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 Cross-Origin Resource Sharing (CORS) (não recomendado). Habilitar CORS está selecionado por padrão.

  Warning

  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 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 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 habilita 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 de eventos 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

• Tipo de Serviço: Selecione serviço OData.

• Atribuir Entidades Jitterbit: Use os menus suspensos para selecionar uma Entidade (Projeto), Operação e Método para o serviço OData:

  • Entidade (Projeto): Selecione entre os projetos implantados que contêm uma operação de entidade API no ambiente onde a API está sendo configurada.

  • Operação: Selecione entre as operações de entidade API do Design Studio implantadas na Entidade (Projeto) selecionada. Apenas uma operação usando cada método pode ser atribuída.

    Importante

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

    • Agentes em nuvem: Para operações de API em um agente em nuvem, o registro de depuração de operação deve estar habilitado na operação.
    • Agentes privados: Para operações de API em um agente privado, ou o registro de depuração de operação deve estar habilitado na operação ou você deve definir EnableLogging=true na seção [APIOperation] do arquivo de configuração do agente privado.

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

  • Método: Selecione um dos GET, PUT, POST, DELETE, PATCH, MERGE ou ALL como o método a ser criado para a Operação selecionada. Selecionar ALL criará métodos separados GET, PUT, POST, DELETE, PATCH e MERGE para a Operação selecionada.

• Atribuir Entidade: Uma vez que todos os dropdowns estejam preenchidos, clique em Atribuir Entidade para adicionar a entidade à tabela abaixo. Pelo menos uma entidade deve ser adicionada para habilitar o botão Próximo.

  Nota

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

• Entidades Atribuídas: Uma tabela exibe todas as entidades que foram atribuídas. Para remover uma entidade atribuída, clique no ícone de remover .

• 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

• Atribuir Funções de Usuário: Selecione as funções da organização cujos membros terão acesso à API a partir das páginas do Gerenciador de API listadas abaixo. As funções disponíveis são aquelas definidas na página Gerenciamento de Usuários do Console de Gerenciamento.

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

  • APIs
  • Gerenciador de Portal, incluindo a geração de documentação da API
  • Portal
  • Logs da API
  • Análises

  O acesso à página 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 desmarcadas. (No exemplo de captura de tela mostrado acima, as funções Administrador e Operações não podem ser desmarcadas 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 o acesso contínuo a todos os usuários.

• Atribuir Perfil 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. 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á desativada.

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

• 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

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

  • Descrição, Tempo Limite, Apenas SSL, CORS Habilitado e Registro Verboso 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 Etapa 1: Configurações.
  • Habilitar Modo de Depuração Até: Esta opção é a mesma que a descrita em Etapa 1: Configurações. Você pode alterar esta configuração diretamente nesta etapa, em vez de ser necessário retornar à primeira etapa.

• Operações: As operações atribuídas em Etapa 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 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 em Etapa 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 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 (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 na sua própria Etapa 4: Resumo e confirmação.

• Excluir: Exclui permanentemente a API e fecha a configuração. Uma caixa de 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, ela também é removida do número de URLs de API usadas contra o seu limite de assinatura. Se o status da API era Rascunho no momento da exclusão, o número de URLs de API usadas contra o seu limite de assinatura não muda, pois a API não estava acessível enquanto estava em status de Rascunho.

• Salvar como Rascunho: Salva a API em status de 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 em status de 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. Uma caixa de diálogo indica que a API está ao vivo:

  

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

• Gerar Documento OpenAPI: Abre a página Portal Manager, onde é possível gerar a documentação da API para a página Portal. Embora este link apareça para serviços OData, a documentação OpenAPI pode ser gerada apenas para APIs personalizadas.
• Dispensar: Fecha o diálogo.

Consultas de serviço OData

Dependendo do banco de dados, é possível filtrar os dados retornados anexando parâmetros de consulta OData (como $count, $inlinecount e $filter) a uma URL de serviço OData.

Editar a API

Após salvar o serviço OData, é possível editá-lo a partir destes locais:

• Usando a visualização em blocos na página de APIs, clique em Visualizar/Editar.
• Usando a visualização em lista na página de APIs, clique em Editar na coluna Ações.