API de monitoramento do serviço de qualificação entitlement-service-monitoring-api

Visão geral da API api-overview

O ESM (Monitoramento do Serviço de Qualificação) foi implementado como um projeto WOLAP (Web Online Analytical Processing). O ESM é uma API da Web genérica para relatórios de negócios apoiada por um data warehouse. Ela age como uma linguagem de consulta HTTP que permite que operações OLAP típicas sejam executadas RESTfully.

A API ESM fornece uma exibição hierárquica dos cubos OLAP subjacentes. Cada recurso (dimensão na hierarquia de dimensão, mapeado como um segmento de caminho de URL) gera relatórios com métricas (agregadas) para a seleção atual. Cada recurso aponta para seu recurso pai (para roll-up) e seus sub-recursos (para drill-down). O corte e a divisão são obtidos por meio de parâmetros de sequência de consulta que fixam dimensões a valores ou intervalos específicos.

A API REST fornece os dados disponíveis dentro de um intervalo de tempo especificado na solicitação (recorrendo aos valores padrão se nenhum for fornecido), de acordo com o caminho da dimensão, os filtros fornecidos e as métricas selecionadas. O intervalo de tempo não será aplicado a relatórios que não contêm dimensões de tempo (ano, mês, dia, hora, minuto, segundo).

O caminho raiz do URL do ponto de extremidade retornará as métricas agregadas gerais em um único registro, juntamente com os links para as opções de detalhamento disponíveis. A versão da API é mapeada como o segmento à direita do caminho URI do endpoint. Por exemplo, https://mgmt.auth.adobe.com/esm/v3 significa que os clientes acessarão o WOLAP versão 3.

Os caminhos de URL disponíveis são detectáveis por meio de links contidos na resposta. Os caminhos de URL válidos são mantidos para mapear um caminho na árvore de detalhamento subjacente que contém (pré-) métricas agregadas. Um caminho no formulário /dimension1/dimension2/dimension3 refletirá uma pré-agregação dessas três dimensões (o equivalente de um SQL clause GROUP BY dimension1, dimension2, dimension3). Se essa pré-agregação não existir e o sistema não puder calculá-la dinamicamente, a API retornará uma resposta 404 Não encontrado.

Árvore de detalhamento drill-down-tree

As árvores de detalhamento a seguir ilustram as dimensões (recursos) disponíveis no ESM 3.0 para Programadores e MVPDs.

Dimension disponível para programadores progr-dimensions

Dia

Hora

Minuto

Dimension disponível para MVPDs mvpd-dimensions

Uma GET para o ponto de extremidade de API https://mgmt.auth.adobe.com/esm/v3 retornará uma representação contendo:

Seguindo um caminho detalhado (passo a passo):
/dimensionA/year/month/day/dimensionX recupera o seguinte
resposta:

Filtros

Exceto para as dimensões de data/hora, qualquer dimensão disponível para a projeção atual (caminho da dimensão) pode ser filtrada usando seu nome como um parâmetro de sequência de consulta.

As seguintes opções de filtro estão disponíveis:

Também há um uso especial para os nomes de dimensão na sequência de consulta: se o nome da dimensão for usado como um parâmetro da sequência de consulta sem valor, isso instruirá a API a retornar uma projeção que inclua essa dimensão no relatório.

Exemplo de consultas ESM

Os parâmetros de cadeia de caracteres de consulta a seguir têm significados reservados para a API (e, portanto, não podem ser usados como nomes de dimensão, caso contrário, nenhuma filtragem será possível para essa dimensão).

Parâmetros de string de consulta reservados para a API ESM

O único método HTTP disponível atualmente é o GET.

Códigos de status da API ESM esm-api-status-codes

Formatos de dados data-formats

Os dados estão disponíveis nos seguintes formatos:

As estratégias de negociação de conteúdo a seguir podem ser usadas pelos clientes (a precedência é dada pela posição na lista - primeiros itens primeiro):

A "extensão" e o parâmetro de consulta suportam os seguintes valores:

Se nenhum tipo de mídia for especificado por nenhuma das estratégias, a API produzirá o conteúdo JSON por padrão.

Idioma do Aplicativo de Hipertexto hypertext-application-language

Para JSON e XML, a carga será codificada como HAL, conforme descrito aqui: http://stateless.co/hal_specification.html.

O relatório real (uma tag/propriedade aninhada chamada "relatório") consistirá na lista real de registros que contém todas as dimensões e métricas selecionadas/aplicáveis com seus valores, codificados da seguinte maneira:

JSON

 "report": [
  {
    "dimension1": "d1",
    ...
    "metric1": "m1",
    ...
  }, {
    ...
  }
]

XML

 <report>
  <record dimension1="d1" ... metric1="m1" ... />
  ...
</report

Para formatos XML e JSON, a ordem dos campos (dimensões e métricas) em um registro não é especificada, mas é consistente (a ordem será a mesma em todos os registros). No entanto, os clientes não devem confiar em nenhuma ordem específica dos campos em um registro.

O link de recurso (o rel "self" em JSON e o atributo de recurso "href" em XML) contém o caminho atual e a sequência de consulta usada para o relatório em linha. A sequência de consulta revelará todos os parâmetros implícitos e explícitos, para que a carga aponte explicitamente o intervalo de tempo usado, os filtros implícitos (se houver) e assim por diante. O restante dos links no recurso conterá todos os segmentos disponíveis que podem ser seguidos para detalhar os dados atuais. Um link para roll-up também será fornecido e apontará para o caminho principal (se houver). O valor href dos links de detalhamento/rollup contém apenas o caminho da URL (ele não inclui a cadeia de caracteres de consulta, portanto, ele precisa ser anexado pelo cliente, se necessário). Observe que nem todos os parâmetros da cadeia de caracteres de consulta usados (ou implícitos) pelo recurso atual serão aplicáveis a links de "acúmulo" ou "detalhamento" (por exemplo, os filtros podem não se aplicar a sub ou superrecursos).

Exemplo (supondo que tenhamos uma única métrica chamada clients e haja uma pré-agregação para year/month/day/...):

   <resource href="/esm/v3/year/month?start=2024-07-20T00:00:00&end=2024-08-20T14:35:21">
   <links>
   <link rel="roll-up" href="/esm/v3/year"/>
   <link rel="drill-down" href="/esm/v3/year/month/day"/>
   </links>
   <report>
   <record month="6" year="2024" clients="205"/>
   <record month="7" year="2024" clients="466"/>
   </report>
   </resource>

CSV

No formato de dados CSV, nenhum link ou outro metadado (exceto a linha de cabeçalho) será fornecido em linha; em vez disso, os metadados de seleção serão fornecidos no nome do arquivo, que seguirá este padrão:

    esm__<start-date>_<end-date>_<filter-values,...>.csv

O CSV conterá uma linha de cabeçalho e, em seguida, os dados do relatório como linhas subsequentes. A linha de cabeçalho conterá todas as dimensões seguidas por todas as métricas. A ordem de classificação dos dados do relatório será refletida na ordem das dimensões. Portanto, se os dados forem classificados por D1 e depois por D2, o cabeçalho CSV será semelhante a: D1, D2, ...metrics....

A ordem dos campos na linha de cabeçalho refletirá a ordem de classificação dos dados da tabela.

Exemplo: https://mgmt.auth.adobe.com/esm/v3/year/month.csv produzirá um arquivo chamado report__2024-07-20_2024-08-20_1000.csv com o seguinte conteúdo:

Atualização de dados data-freshness

As respostas HTTP bem-sucedidas contêm um cabeçalho Last-Modified que indica a hora em que o relatório no corpo foi atualizado pela última vez. A falta de um cabeçalho Última modificação indica que os dados do relatório são calculados em tempo real.

Normalmente, os dados granulares serão atualizados com menos frequência do que os dados granulares (por exemplo, valores por minuto ou valores por hora, podem estar mais atualizados do que os valores diários, especialmente para métricas que não podem ser computadas com base em granularidades menores, como contagens exclusivas).

Compactação GZIP gzip-compression

A Adobe recomenda que você ative o suporte ao gzip nos clientes que buscam relatórios ESM. Isso reduzirá muito o tamanho da resposta, o que, por sua vez, reduzirá seu tempo de resposta. (A taxa de compactação dos dados ESM está no intervalo de 20 a 30.)

Para habilitar a compactação gzip no cliente, defina o cabeçalho Accept-Encoding: da seguinte maneira: