Página de logs da API no Jitterbit API Manager

Introdução

A página Logs da API dentro do API Manager exibe uma tabela de todos os logs de processamento da API, bem como logs de depuração (se o registro de depuração estiver ativado). Os logs são exibidos para APIs personalizadas, OData e proxy quando são chamados através do gateway de API em nuvem ou gateway de API privado.

Existem quatro tipos de logs que podem ser registrados para uma chamada de API:

• Logs da API: Os logs da API são gerados automaticamente na página Logs da API para cada chamada de API do API Manager. Os logs da API contêm informações sobre a chamada da API, incluindo o timestamp da solicitação da 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 da aplicação que faz a chamada, a aplicação de origem e quaisquer mensagens de log.
• Logs de Depuração da API: Os logs de depuração da API são entradas adicionais em um log de API existente que rastreiam completamente cada solicitação recebida através da URL de serviço da API do API Manager. O registro de depuração da API não está ativado por padrão e deve ser habilitado em uma API do API Manager individual para que os logs de depuração da API sejam incluídos em um log de API.
• Logs Verbosos da API: Os logs verbosos da API são entradas adicionais em um log de API existente que consistem em dados de solicitação e resposta recebidos ou enviados através da URL de serviço da API do API Manager. O registro verboso da API não está ativado por padrão e deve ser habilitado em uma API do API Manager individual para que os logs verbosos da API sejam incluídos em um log de 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 da API, logs de depuração e logs verbosos, os logs de operação da API requerem 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 arquivo jitterbit.log localizado no diretório log.

Os dados de registro para logs da API, logs de depuração e logs verbosos estão disponíveis na página Logs da API por 90 dias a partir da data em que a API é consumida.

Para mais informações sobre como habilitar logs de depuração e logs detalhados, consulte estes recursos:

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

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

Acesse a página de Logs da API

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

Cabeçalho da página de Logs da API

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

Você pode ajustar os dados exibidos usando os dropdowns Filtrar por e Ver Dados.

Filtrar por

Os dropdowns Filtrar por permitem exibir logs da 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 dos quais você pode selecionar um ou vários critérios.

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

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

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

  Nota

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

• Perfis: Use o menu suspenso para selecionar os perfis de segurança atribuídos das APIs. Quando todos os filtros estã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, escolhendo entre Sucesso (2xx), Redirecionamentos (3xx), Erros do Cliente (4xx) e Erros do Servidor (5xx). Quando todos os filtros estã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 mais informações sobre códigos de status, veja definições de códigos de status w3.org.

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

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

View Data

A opção View Data permite exibir logs dentro de um período específico de tempo. A configuração padrão para o período de tempo é Últimos 7 Dias.

Use o menu suspenso View Data 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 exibir logs da API dentro de um período de tempo especificado nos últimos 90 dias. Quando esta opção é selecionada, campos adicionais de calendário De e Para são exibidos:

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

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

Pesquisa

A barra de pesquisa permite filtrar os logs pelos critérios de pesquisa fornecidos abaixo:

• Apenas Logs com Mensagens: Selecione para restringir ainda mais os resultados da pesquisa apenas para logs que incluem detalhes de registro. 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:

Combine searches

As pesquisas podem conter uma combinação de critérios. Os critérios de pesquisa combinados devem ser separados por um 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%;

Additional options

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

• View last refreshed: Exibe a última vez que os dados foram atualizados, seja dinamicamente ou manualmente. O horário é exibido no formato h:mm:ss.

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

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

  Nota

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

View API logs

Cada linha na tabela API Logs exibe dados de registro da 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.
• Status Code: O código de status HTTP. Para mais informações sobre códigos de status HTTP, consulte definições de códigos de status w3.org.
• Request ID: Um ID único para a solicitação da API.
• Request Method: O método de solicitação HTTP da API (GET, PUT, POST, DELETE, PATCH ou MERGE).
• Request URI: A URL completa da API que foi chamada. Passe o mouse sobre o campo Request URI para visualizar a URL completa.
• Response Time: A quantidade de tempo, em milissegundos, que a API levou para executar.
• Source IP: O endereço IP externo da aplicação ou servidor que chamou a API.
• Source Application: A aplicação de origem da chamada da API, presente apenas quando a chamada da 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 dos critérios de filtro e pesquisa usando os botões Próximo e Anterior.

Ver detalhes do log

Para ver detalhes adicionais do log ou logs de depuração (se habilitados), clique no ícone de expandir em uma entrada de log:

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

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

Quando o registro de depuração está habilitado para uma API e a carga útil da API contém mais de 10.000 caracteres, um botão Baixar Carga Útil fica visível para a entrada do log. Quando clicado, um arquivo ZIP da carga útil da API é baixado para sua máquina local.

API Manager Log Service API (Beta)

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

Para usar a API Manager Log Service API (Beta), após habilitar logs de API para a API Manager API (descrito anteriormente nesta página), siga estas etapas:

1. Recupere um token de autenticação usando a API do Controlador de Serviço de Usuário. Este token é necessário para usar a API Manager Log Service API (Beta).

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

   • Se sua organização Harmony tiver a TFA habilitada, recuperar o token de autenticação requer duas solicitações:

     1. Recuperar um código TFA

     2. Usar 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 Gerenciador de API (Beta).

Recuperar um token de autenticação

Recuperar um token de autenticação requer o uso da API do Controlador de Serviço de 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

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

Cabeçalhos

Esses cabeçalhos são obrigatórios:

Parâmetros do corpo

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

Corpo da resposta

O corpo da resposta retornada contém uma lista das organizações com as quais o usuário está associado, além do token de autenticação ("authenticationToken"). Este token é necessário para a autorização subsequente com a API do Log Service 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 organização do usuário no Harmony tiver a autenticação de dois fatores (TFA) habilitada, a recuperação do token de autenticação requer duas solicitações usando a API do User Service Controller:

1. Recuperar um código TFA

2. Usar 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 a TFA está habilitada. 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

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

Cabeçalhos

Esses cabeçalhos são necessários:

Parâmetros do corpo

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

Corpo da resposta

O corpo da resposta retornada contém uma mensagem de erro indicando que um código TFA foi enviado para o endereço de 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 para o endereço de email do usuário pode agora 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/tfacode' \
--header 'Content-Type: application/json' \
--data-raw '{
    "email": "alice@jbexample.com",
    "password": "Jitterbit4Ever!",
    "code": "112233",
    "deviceId": "abcd"
}'

URL Base

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

Cabeçalhos

Esses cabeçalhos são obrigatórios:

Parâmetros do corpo

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

Corpo da resposta

O corpo da resposta retornada contém uma lista das organizações com as quais o usuário está associado, além do token de autenticação ("authenticationToken"). Esse token é necessário para a autorização subsequente com a API do Serviço de Log do Gerenciador de API (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 da API de forma assíncrona (Beta)

Uma vez que você tenha o token de autenticação e o ID da organização, é possível recuperar logs da API de forma assíncrona usando a API do Serviço de Logs do Gerenciador de 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

A 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 do corpo

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

Corpo da resposta

Se bem-sucedido, o corpo da resposta retornada contém 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 ser fornecida como parte da seguinte chamada da API para verificar o status do arquivo de log ou para baixá-lo se o status for COMPLETE:

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.
• PROCESSING: O arquivo de log está sendo gerado. O status mudará para COMPLETE quando a geração do arquivo estiver completa.
• COMPLETE: O arquivo de log está pronto para ser baixado usando a API log-async acima.
• INVALID: A chave de referência não pôde ser encontrada. Este status é relatado apenas se uma chave de referência desconhecida ou malformada for fornecida à API log-async.
• ERROR: A chave de referência foi encontrada após a API terminar 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 original da API retornaram 0 resultados.