API de uso de monitoramento de simultaneidade cmu-api-usage

Visão geral da API api-overview

O CMU (Monitoramento de Simultaneidade de Uso) é implementado como um projeto WOLAP (Web-based Online Analytical Processing). A CMU é uma API da Web de geração de relatórios comerciais genérica suportada 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 CMU 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/cmu/v2 significa que os clientes acessarão o WOLAP versão 2.

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 formato /dimension1/dimension2/dimension3 refletirá uma pré-agregação dessas três dimensões (o equivalente de uma cláusula SQL 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 na CMU 2.0:

Dimension disponíveis para locatários CM

Um GET para o ponto de extremidade de API https://mgmt.auth.adobe.com/cmu/v2 retornará uma representação contendo:

Seguindo um caminho de detalhamento (passo a passo): /dimensionA/year/month/day/dimensionX recupera a 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 CMU:

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

O único método HTTP disponível atualmente é o GET. Suporte para métodos OPTIONS / HEAD pode ser fornecido em versões futuras.

Códigos de status da API CMU cmu-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.

HAL (Hypertext Application Language, Linguagem de Aplicativo de Hipertexto) hypertext-app-lang

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 json

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

XML 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 clientes e haja uma pré-agregação para year/month/day/...):

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

report__<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 terá esta aparência: 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/cmu/v2/year/month.csv produzirá um arquivo chamado report__2012-07-20_2012-08-20_1000.csv com o seguinte conteúdo:

Atualização de dados data-freshness

Embora a solicitação contenha um cabeçalho Última Modificação, ela NÃO reflete a hora em que o relatório no corpo foi atualizado pela última vez. Os relatórios gerais estão sendo calculados regularmente, com as seguintes regras:

Os relatórios de nível de atividade e nível de simultaneidade são atualizados todos os dias, independentemente da granularidade de tempo.

Compactação GZIP gzip-compression

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

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

Accept-Encoding: gzip, deflate

Informações relacionadas related-information