Registros de API

Introdução

A página API Logs dentro do API Manager exibe uma tabela de todos os logs de processamento da API, bem como logs de depurar (se o log de depurar estiver habilitado). Os logs são exibidos para APIs personalizadas, OData e proxy quando são chamadas por meio do cloud API gateway ou gateway de API privado.

Há quatro tipos de logs que podem ser gravados para uma chamada de API:

• Logs de API: Os logs de API são gerados automaticamente na página Logs de API para cada chamada de API do API Manager. Os logs de API contêm informações sobre a chamada de API, incluindo o registro de data e hora da solicitação de API, o código de status HTTP, o ID da solicitação, o método da solicitação, o URI da solicitação, o tempo de resposta, o IP de origem do aplicativo de chamada, o aplicativo de origem e quaisquer mensagens de log.
• Logs de depuração da API: Os logs de depurar da API são entradas adicionais em um log de API existente que rastreiam completamente cada solicitação recebida por meio de uma URL de serviço da API do API Manager. O log de depurar da API não é habilitado por padrão e deve ser habilitado em uma API individual do API Manager para que os logs de depurar da API sejam incluídos em um log de API.
• Logs detalhados da API: Os logs detalhados da API são entradas adicionais em um log da API existente que consistem em dados de solicitação e resposta recebidos ou enviados por meio de uma URL de serviço da API do API Manager. O log detalhado da API não é habilitado por padrão e deve ser habilitado em uma API individual do API Manager para que os logs detalhados da API sejam incluídos em um log da API.
• Logs de operação da API: Os logs de operação da API contêm o início de uma chamada de API e o tempo decorrido. Ao contrário dos logs de API, logs de depurar e logs verbose, os logs de operação da API exigem o uso de um agente privado e são habilitados no arquivo de configuração do agente privado. Esses logs são registrados no agente privado no jitterbit.log arquivo localizado no log diretório.

Os dados de registro para logs de API, logs de depurar e logs detalhados ficam disponíveis na página Logs de API por 90 dias a partir da data em que a API é consumida.

Para obter mais informações sobre como habilitar logs de depurar e logs detalhados, consulte estes recursos:

• Etapa 1: Configurações de configuração de API personalizada
• Etapa 1: Configurações de configuração do serviço OData
• Etapa 1: Configurações básicas de configuração da API de proxy

Para adicionar informações de log adicionais para APIs OData, incluindo dados SQL enviados ao banco de dados, edite o arquivo de configuração do agente privado e definir DebugJDML para true.

Acesse a Página de Logs da API

A página API Logs pode ser acessada pelo menu do portal Harmony ou pelo menu de navegação do API Manager:

• Use o menu do portal Harmony para selecionar API Manager > API Logs:

  

• Ao acessar uma página do API Manager, use seu menu de navegação para selecionar API Logs:

  

Cabeçalho da Página de Logs da API

O cabeçalho na parte superior da página Logs da API inclui o menu de navegação do API Manager, uma barra de pesquisa, filtros e opções adicionais:

Você pode ajustar os dados exibidos usando os menus suspensos Filtrar por e Exibir dados.

Filtrar por

Os menus suspensos Filtrar por permitem que você exiba logs de API com base em critérios específicos em qualquer combinação de ambientes, APIs, perfis, códigos de status ou métodos de solicitação.

Cada filtro exibe uma lista suspensa de critérios da qual você pode selecionar um ou vários critérios.

Estes são os critérios disponíveis para filtrar:

• Ambientes: Use o menu suspenso para selecionar ambientes onde as APIs estão localizadas. Quando todos os filtros são desmarcados, os ambientes para todas as APIs na organização às quais você tem acesso são exibidos.

• APIs: Use o menu suspenso para selecionar APIs publicadas dentro da organização. Quando todos os filtros estiverem desmarcados, todas as APIs na organização às quais você tem acesso serão exibidas.

  Nota

  APIs publicadas anteriormente que se tornarem não publicadas não aparecerão no menu suspenso APIs. Os logs de API para essas APIs estarão presentes na página Logs de API, mas não poderão ser filtrados.

• Perfis: Use o menu suspenso para selecionar os perfis de segurança atribuídos das APIs. Quando todos os filtros são desmarcados, todos os perfis de segurança na organização aos quais você tem acesso são exibidos.

• Códigos de status: Use o menu suspenso para selecionar os grupos de códigos de status de resposta HTTP, selecionando entre Sucesso (2xx), Redirecionamentos (3xx), Erros do cliente (4xx) e Erros do servidor (5xx). Quando todos os filtros são desmarcados, todos os códigos de status de resposta HTTP para APIs nas organizações às quais você tem acesso são exibidos. Para obter mais informações sobre códigos de status, consulte definições de código de status do w3.org.

• Métodos de solicitação: Use o menu suspenso para selecionar os métodos de solicitação HTTP, selecionando entre GET, PUT, POST, DELETE, PATCH e MERGE. Quando todos os filtros são desmarcados, todos os métodos de solicitação HTTP para APIs na organização à qual você tem acesso são exibidos. Para obter mais informações sobre métodos de solicitação HTTP, consulte métodos de solicitação do w3.org.

• Gateway de API: Visível somente quando uma organização usa dois ou mais gateways de API de nuvem. Use o menu para selecionar o domínio do gateway de API de nuvem. A tabela API Logs exibirá logs somente para o domínio selecionado.

Exibir Dados

A opção Exibir Dados permite que você exiba logs dentro de um período de tempo específico. A configuração padrão para o período de tempo é Últimos 7 Dias.

Use o menu suspenso Exibir dados para selecionar o período de tempo desejado. Selecione um dos Últimos 10 minutos, Última 1 hora, Últimas 10 horas, Últimas 24 horas, Últimos 7 dias, Último 1 mês ou Período personalizado.

Selecionar Período Personalizado permite que você exiba logs de API dentro de um período de tempo especificado. Quando essa opção é selecionada, campos de calendário adicionais De e Para são exibidos:

• De: Clique para ajustar a data e a hora de início dos logs da API.
• Para: Clique para ajustar a data e a hora de término dos logs da API.

Após clicar nos campos de calendário De ou Para, uma caixa de diálogo de calendário é exibida, onde você seleciona a data e a hora:

Procurar

A barra de pesquisa permite que você filtre os logs pelos critérios de pesquisa fornecidos abaixo:

• Somente logs com mensagens: Selecione para restringir ainda mais os resultados da pesquisa apenas a logs que incluem detalhes de log. Os resultados da pesquisa serão atualizados automaticamente.

Critérios de Pesquisa

Estes são os critérios de pesquisa que podem ser usados. Exemplos de critérios de pesquisa válidos e inválidos estão incluídos:

Combinar Pesquisas

As pesquisas podem conter uma combinação de critérios. Os critérios de pesquisa combinados devem ser separados por ponto e vírgula (;) entre cada critério. Estes são exemplos de pesquisas combinadas válidas:

message=%Access Denied%;requesturi=%contacts%;

requestid=%yzaccwui%;message=%REJECT%;
requesturi=%contacts%;responsetime<=2;
responsetime>=5;sourceapp=%Chrome%;
responsetime>=5;sourceip=70.5%;
sourceapp=%Chrome%;message=%REJECT%;

sourceapp=%Mozilla%;responsetime<=1;

sourceip=70.5%;requesturi=%contacts%;

Opções Adicionais

Opções adicionais de log de API são exibidas no lado esquerdo da página, logo acima da barra de pesquisa:

• Exibir última atualização: Exibe a última vez que os dados foram atualizados dinamicamente ou manualmente. O horário é exibido no formato h:mm:ss.

• Atualizar: Clique para atualizar os dados de log com base nos filtros aplicados e critérios de pesquisa.

• Baixar como CSV: Clique para baixar os dados de log atuais com base nos filtros aplicados e critérios de pesquisa.

  Nota

  O campo de data dentro do arquivo CSV é um registro de data e hora UNIX que exigirá conversão se você quiser usar um formato de data e hora diferente.

Exibir Logs da API

Cada linha na tabela API Logs exibe dados de registro de API para uma chamada de API:

• Time Stamp: O timestamp da solicitação da API. Os horários são exibidos no fuso horário do seu navegador.
• Código de status: O código de status HTTP. Para mais informações sobre códigos de status HTTP, veja definições de código de status w3.org.
• ID da solicitação: Um ID exclusivo para a solicitação da API.
• Método de solicitação: O método de solicitação HTTP da API (GET, PUT, POST, DELETE, PATCH ou MERGE).
• URI de solicitação: A URL completa da API que foi chamada. Passe o mouse sobre o campo URI de solicitação para visualizar a URL completa.
• Tempo de resposta: A quantidade de tempo, em milissegundos, que a API levou para ser executada.
• IP de origem: O endereço IP externo do aplicativo ou servidor que chamou a API.
• Source Application: O aplicativo de origem para a chamada de API, presente somente quando a chamada de API está sendo passada em um cabeçalho de solicitação. Passe o mouse sobre a coluna Source Application para visualizar o conteúdo do campo.

Cada página exibe 20 logs. Você pode visualizar todos os logs dentro do filtro e critérios de busca usando os botões Próximo e Anterior.

Ver Detalhes do Log

Para visualizar detalhes adicionais do log ou logs de depurar (se habilitado), clique em expandir ícone em uma entrada de log:

Um log de API típico conterá estes detalhes:

• Nome de domínio da região Harmony, caminho de serviço e URL base (consulte URL do serviço API)
• Tempo de processamento de chamada de API
• Informações do perfil de segurança, como tipo de autorização e credenciais usadas
• Detalhes da carga útil, incluindo o comprimento da payload e o tamanho da resposta
• Informações de erro (se aplicável)
• Logs de depuração (se habilitados)
• Logs detalhados (se habilitados)

API do Serviço de Log do API Manager (beta)

Como alternativa ao download de um arquivo de log de API clicando em Download as CSV, você pode recuperar um arquivo de log de API usando uma REST API. Isso requer o uso de utilitários de linha de comando, como curl, ou aplicativos como Postman.

Para usar a API do serviço de log do API Manager (beta), após habilitar os logs da API para a API do API Manager (descrita anteriormente nesta página), siga estas etapas:

1. Recupere um token de autenticação usando a API User Service Controller. Esse token é necessário para usar a API do API Manager Log Service (beta).

   • Se sua Harmony organização não tem autenticação de dois fatores (TFA) habilitada, recupere seu token de autenticação com uma solicitação de login padrão.

   • Se sua Harmony organização tem o TFA habilitado, recuperando o token de autenticação requer duas solicitações:

     1. Recuperar um código TFA

     2. Use o código TFA para recuperar um token de autenticação

2. Recuperar o arquivo de log usando a API do Serviço de Log do API Manager (beta).

Recuperar um Token de Autenticação

A recuperação de um token de autenticação requer o uso da API do Controlador de Serviço do Usuário.

Um exemplo de solicitação mostrando o login na região NA e a recuperação do token de autorização:

curl --location --request PUT 'https://na-east.jitterbit.com/jitterbit-cloud-restful-service/user/login' \
--header 'Content-Type: application/json' \
--data-raw '{
    "email": "alice@jbexample.com",
    "password": "Jitterbit4Ever!"
}'

URL Base

O URL base depende da região em que a organização está localizada:

Cabeçalhos

Estes cabeçalhos são obrigatórios:

Parâmetros Corporais

Esses parâmetros obrigatórios são passados no corpo da solicitação:

Corpo de Resposta

O corpo da resposta retornado contém uma lista das organizações às quais o usuário está associado, além do token de autenticação ("authenticationToken"). Este token é necessário para autorização subsequente com a API do serviço de log do API Manager (beta). Neste exemplo, o token de autenticação é "1_70dfe7f7-1d47-4ad5-be5d-bc4a222dd2g4". O ID da organização é mostrado como "123456" para a primeira organização à qual este usuário pertence. Um exemplo da resposta:

{
  "status": true,
  "operation": "User login",
  "authenticationToken": "1_70dfe7f7-1d47-4ad5-be5d-bc4a222dd2g4",
  "serverUrl": "https://na-east.jitterbit.com",
  "cloudAppsUrl": "https://na-east.jitterbit.com",
  "orgAttrs": [
    {
      "orgId": "123456",
      "orgName": "JB Example Company",
      "orgZoneUrl": "https://na-east.jitterbit.com"
    },
    {
      "orgId": "20970",
      "orgName": "example@jbexample.com",
      "orgZoneUrl": "https://na-east.jitterbit.com"
    }
  ],
  "defaultOrgId": "123456",
  "sessionTimeoutInSeconds": 14400
}

Recuperar um Token de Autenticação com TFA Habilitado

Se a Harmony organização de um usuário tem autenticação de dois fatores (TFA) habilitada, a recuperação do token de autenticação requer duas solicitações usando a API do Controlador de Serviço do Usuário:

1. Recuperar um código TFA

2. Use o código TFA para recuperar um token de autenticação

Recuperar um Código TFA

Um código TFA válido é necessário para recuperar um token de autenticação quando o TFA está habilitado. Um exemplo de solicitação mostrando o login na região NA e a solicitação de um código TFA:

curl --location --request PUT 'https://na-east.jitterbit.com/jitterbit-cloud-restful-service/user/login' \
--header 'Content-Type: application/json' \
--data-raw '{
    "email": "alice@jbexample.com",
    "password": "Jitterbit4Ever!",
    "deviceId": "abcd"
}'

URL Base

O URL base depende da região em que a organização está localizada:

Cabeçalhos

Estes cabeçalhos são obrigatórios:

Parâmetros Corporais

Esses parâmetros obrigatórios são passados no corpo da solicitação:

Corpo de Resposta

O corpo da resposta retornada contém uma mensagem de erro indicando que um código TFA foi enviado para o endereço email do usuário.

{
  "status": false,
  "operation": "User login",
  "errorCode": "VALIDATE_TFA_LOGIN_EMAIL",
  "errorMessage": "Validate your login with authentication code. An email from Jitterbit with the code was sent to you.",
  "authenticationToken": null,
  "serverUrl": "https://na-east.jitterbit.com",
  "orgAttrs": [],
  "defaultOrgId": null
}

Use o Código TFA para Recuperar um Token de Autenticação

O código TFA enviado ao endereço email do usuário agora pode ser usado na segunda solicitação para recuperar o token de autenticação. Um exemplo de solicitação mostrando o login na região NA com um código TFA e a recuperação do token de autorização:

curl --location --request PUT 'https://na-east.jitterbit.com/jitterbit-cloud-restful-service/user/login/code' \
--header 'Content-Type: application/json' \
--data-raw '{
    "email": "alice@jbexample.com",
    "password": "Jitterbit4Ever!",
    "code": "112233"
    "deviceId": "abcd"
}'

URL Base

O URL base depende da região em que a organização está localizada:

Cabeçalhos

Estes cabeçalhos são obrigatórios:

Parâmetros Corporais

Esses parâmetros obrigatórios são passados no corpo da solicitação:

Corpo de Resposta

O corpo da resposta retornado contém uma lista das organizações às quais o usuário está associado, além do token de autenticação ("authenticationToken"). Este token é necessário para autorização subsequente com a API do serviço de log do API Manager (beta). Neste exemplo, o token de autenticação é "1_70dfe7f7-1d47-4ad5-be5d-bc4a222dd2g4". O ID da organização é mostrado como "123456" para a primeira organização à qual este usuário pertence. Um exemplo da resposta:

{
  "status": true,
  "operation": "User login",
  "authenticationToken": "1_70dfe7f7-1d47-4ad5-be5d-bc4a222dd2g4",
  "serverUrl": "https://na-east.jitterbit.com",
  "cloudAppsUrl": "https://na-east.jitterbit.com",
  "orgAttrs": [
    {
      "orgId": "123456",
      "orgName": "JB Example Company",
      "orgZoneUrl": "https://na-east.jitterbit.com"
    },
    {
      "orgId": "654321",
      "orgName": "example@jbexample.com",
      "orgZoneUrl": "https://na-east.jitterbit.com"
    }
  ],
  "defaultOrgId": "123456",
  "sessionTimeoutInSeconds": 14400
}

Recuperar Logs de API de Forma Assíncrona (beta)

Depois de ter o token de autenticação e o ID da organização, você pode recuperar logs de API de forma assíncrona usando a API Manager Log Service API (beta). Um exemplo mostrando a recuperação de todos os registros de 20 de janeiro de 2023 a 20 de janeiro de 2024:

curl --location --request PUT 'https://na-east.jitterbit.com/jitterbit-cloud-restful-service/api/analytics/debuglogs-async' \
--header 'Content-Type: application/json' --header 'Accept: application/json' --header 'authToken: 1_70dfe7f7-1d47-4ad5-be5d-bc4a222dd2g4' \
--data-raw '{
    "ascendSort": false,
    "retrieveLogMessages": false,
    "timeRangeFrom": "01/20/2023 01:01:00 +0100",
    "timeRangeTo": "01/20/2024 01:01:00 +0100",
    "clientTimeZone": "Europe/Berlin",
    "queryString": "responsetime>5; sourceip=14.141%",
    "orgId": "123456",
    "csvFormat": true
}'

URL Base

O URL base depende da região em que a organização está localizada:

Cabeçalhos

Esses cabeçalhos podem ser usados na solicitação:

Parâmetros Corporais

Esses parâmetros podem ser passados no corpo da solicitação:

Corpo de Resposta

Se for bem-sucedido, o corpo da resposta retornado conterá uma chave de referência para rastrear e baixar o arquivo de log da API com base nos parâmetros fornecidos:

{
    "key": "debug-log-E8D47FE1F172D3EE46C620791E614B78D111CE624485D2E1B3D482370690DC40",
    "status": "COMPLETE"
}

A chave de referência pode então ser fornecida como parte da seguinte chamada de API para verificar o status do arquivo de log ou para baixá-lo se o status for COMPLETO:

curl --location --request GET 'https://na-east.jitterbit.com/jitterbit-cloud-restful-service/api/analytics/log-async/{orgId}/{key}' \
--header 'Content-Type: application/json' --header 'Accept: application/json' --header 'authToken: 1_70dfe7f7-1d47-4ad5-be5d-bc4a222dd2g4'

Os status possíveis incluem:

• RECEIVED: Harmony recebeu uma solicitação válida para gerar o arquivo de log. O status mudará para PROCESSING quando a solicitação estiver sendo executada.
• PROCESSANDO: O arquivo de log está sendo gerado. O status mudará para COMPLETO quando a geração do arquivo estiver concluída.
• COMPLETO: O arquivo de log está pronto para ser baixado usando o log-async API acima.
• INVÁLIDO: A chave de referência não pôde ser encontrada. Este status é relatado somente se uma chave de referência desconhecida ou malformada for fornecida ao log-async API.
• ERRO: A chave de referência foi encontrada depois que a API terminou de tentar gerar o arquivo de log, mas um erro foi relatado. Uma mensagem de erro também será retornada detalhando o motivo da falha na geração.
• NO_DATA: Os parâmetros de filtragem que consultam dados na chamada de API original retornaram 0 resultados.