Registros de API¶

Introdução¶

A página Logs de API no API Manager exibe uma tabela de todos os logs de processamento de API, bem como logs de depurar (se o log de depurar estiver ativado). Os registros são exibidos para APIs personalizadas, OData e Proxy quando são chamados por meio 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 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 da API contêm informações sobre a chamada da API, incluindo o carimbo de data/hora 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 do aplicativo de chamada, o aplicativo de origem, e quaisquer mensagens de log.
• Logs de depuração de API: Os logs de depurar de API são entradas adicionais em um log de API existente que rastreiam totalmente cada solicitação recebida por meio de um URL de serviço da API do API Manager. A criação de log de depurar de API não é ativada por padrão e deve ser ativada em uma API individual do API Manager para que os logs de depurar de 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 de API existente que consiste em dados de solicitação e resposta recebidos ou enviados por meio de um URL de serviço da API do API Manager. A criação de log detalhado da API não é ativada por padrão e deve ser ativada 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ções de API: Os logs de operação de 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 detalhados, os logs de operação de 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 de logs de API, logs de depurar e logs detalhados estão 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 ativar logs de depurar e logs detalhados, consulte estes recursos:

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

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 Registros da API¶

A página API Logs pode ser acessada no menu do Harmony Portal ou em outras páginas do API Manager:

• Da Casa ou Downloads ou nas páginas Cloud Studio, Vinyl, Marketplace, Management Console, EDI, ou Citizen Integrator, use o menu Harmony Portal no canto superior esquerdo para acessar API Manager > API Logs:

  

• Em Minhas APIs, Gerenciador do Portal, Análise, Perfis de segurança, Grupos de IPs Confiáveis ou Grupos de API, use o menu de navegação do API Manager para selecionar Logs de API:

  

Cabeçalho da Página de Registros de API¶

O cabeçalho na parte superior da página Logs de 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 exibir 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 na 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 os ambientes onde as APIs estão localizadas. Quando todos os filtros estiverem desmarcados, serão exibidos os ambientes de todas as APIs da organização às quais você tem acesso.

• APIs: Use o menu suspenso para selecionar APIs publicadas na organização. Quando todos os filtros estiverem desmarcados, todas as APIs da organização à qual 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 podem ser filtrados.

• Perfis: Use o menu suspenso para selecionar os perfis de segurança atribuídos às APIs. Quando todos os filtros estiverem desmarcados, todos os perfis de segurança da organização aos quais você tem acesso serã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 estão desmarcados, todos os códigos de status de resposta HTTP para APIs nas organizações às quais você tem acesso serão exibidos. Para obter mais informações sobre códigos de status, consulte status w3.org definições de código.

• 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 estiverem desmarcados, todos os métodos de solicitação HTTP para APIs na organização à qual você tem acesso serão exibidos. Para obter mais informações sobre métodos de solicitação HTTP, consulte métodos de solicitação w3.org.

Ver Dados¶

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

Use o menu suspenso Visualizar dados para selecionar o período desejado. Selecione um dos seguintes Ú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 de API dentro de um período de tempo especificado. Quando esta opção é selecionada, os campos adicionais do calendário De e Para são exibidos:

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

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

Procurar¶

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

• Apenas registros com mensagens: Selecione para restringir ainda mais os resultados da pesquisa apenas a registros que incluam detalhes do 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:

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 da API são exibidas no lado esquerdo da página, diretamente acima da barra de pesquisa:

• Ver última atualização: Exibe a última vez que os dados foram atualizados de forma dinâmica ou manual. A hora é exibida no formato h:mm:ss.

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

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

  Nota

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

Ver Registros de API¶

Cada linha na tabela de logs de API exibe dados de log de API para uma chamada de API:

• Carimbo de data/hora: O carimbo de data/hora 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 obter mais informações sobre códigos de status HTTP, consulte w3.org definições de código de status.
• 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: O URL completo da API que foi chamada. Passe o mouse sobre o campo Request URI para visualizar o URL completo.
• Tempo de resposta: O 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.
• Aplicativo de origem: O aplicativo de origem da chamada de API, presente apenas quando a chamada de API está sendo transmitida em um cabeçalho de solicitação. Passe o mouse sobre a coluna Aplicativo de Origem para visualizar o conteúdo do campo.

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

Ver Detalhes do Registro¶

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

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 chamadas de API
• Informações do perfil de segurança, como tipo de autorização e credenciais usadas
• Detalhes da carga útil, incluindo comprimento da payload e tamanho da resposta
• Informações de erro (se aplicável)
• Logs de depuração (se habilitado)
• Logs detalhados (se habilitado)

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

Como alternativa ao download de um arquivo de log de depurar de API clicando em Fazer download como CSV, você pode recuperar um arquivo de log de depurar 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 API API Manager Log Service (Beta), depois de ativar os logs de depurar da API para a API API 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 API API Manager Log Service (Beta).

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

   • Se a 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 API API Manager Log Service (Beta).

Recuperar um Token de Autenticação¶

A recuperação de um token de autenticação requer o uso da API User Service Controller.

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¶

Estes 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"). Esse token é necessário para autorização subsequente com a API API API Manager Log Service (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 Ativado¶

Se o Harmony organização tem a autenticação de dois fatores (TFA) ativada, a recuperação do token de autenticação requer duas solicitações usando a API User Service Controller:

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¶

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

Corpo de Resposta¶

O corpo da resposta retornado contém uma mensagem de erro indicando que um código TFA foi enviado ao 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¶

Estes 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"). Esse token é necessário para autorização subsequente com a API API API Manager Log Service (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 Depuração de API de Forma Assíncrona (beta)¶

Depois de ter o token de autenticação e o ID da organização, será possível recuperar logs de depurar da API de forma assíncrona usando a API API Manager Log Service (Beta). Um exemplo que mostra 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 fazer download do arquivo de log de depurar 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 fazer download dele 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 possíveis status incluem:

• RECEBIDO: 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 COMPLETE e a geração do arquivo será 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 foi encontrada. Este status só é relatado 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.