customReportValues
Atualizado na API v37.
Categoria
| Recuperação de dados |
Descrição
| Retorna um conjunto de dados para os critérios de relatório solicitados na instância solicitada. |
Permissões obrigatórias para invocar
| Nenhum (o usuário deve ter um conjunto de permissões atribuído) |
Parâmetros obrigatórios na solicitação
| Credenciais, relatório |
Para a API versão 15 e mais recente, chame exportTime para recuperar as IDs de elemento de tempo corretas
Consulte Referência: condições de desempenho de customReportValues para saber como garantir que suas solicitações aproveitem as melhorias de desempenho e escalabilidade lançadas na versão 2023R2 para a API v36.
A solicitação deste método contém uma especificação para um relatório que pode ser usado para pesquisar dados e retornar valores. A API usa números de ID internos como entradas. APIs de recuperação de metadados podem ser chamadas para obter IDs válidas. Os resultados são representados por coordenadas e valores. A resposta também retorna avisos e mensagens de erro, se aplicável.
Essa API é baseada nos relatórios de matriz. A solicitação requer que o autor da chamada especifique elementos no eixo X (colunas), no eixo Y (linhas) e em um eixo de filtro opcional usado para filtrar todos os dados recuperados pela API. Os relatórios de matriz contêm eixos que determinam quais dados aparecem no relatório. Cada eixo define uma borda do relatório. Todos os relatórios de matriz têm três eixos:
- o eixo X (a borda superior). Define o conjunto de colunas no relatório.
- o eixo Y (a borda esquerda). Define o conjunto de linhas em um relatório
- o eixo do filtro, um eixo global que define as propriedades que se aplicam a todos os dados no relatório. Consulte os exemplos de eixos de filtro para obter mais informações.
Um eixo pode ser dividido em vários segmentos. Um segmento é uma forma de separar conjuntos de dimensões em um único eixo. O eixo do filtro pode ter somente um segmento, mas os outros dois eixos podem ter quantos segmentos você desejar.
Cada segmento pode ter um número ilimitado de níveis. Um nível representa uma única dimensão lógica usada para descrever quais elementos dessa dimensão se aplicam às linhas ou colunas abaixo dela. Um segmento pode conter no máximo um nível por dimensão lógica.
Cada nível pode conter um ou mais elementos da dimensão do nível. (Todos os elementos no nível devem pertencer à dimensão especificada no nível.) Um elemento geralmente é um item na dimensão, como uma conta específica na dimensão de conta ou um trimestre fiscal na dimensão de tempo. Esses elementos são usados pelo sistema para selecionar e agregar os dados encontrados no relatório.
Quando um segmento no eixo X ou Y contém vários níveis, os elementos de cada nível são combinados com todos os elementos de todos os outros níveis para formar o produto cartesiano de todas as combinações possíveis de elementos de nível. Cada coluna ou linha representa uma combinação possível de elementos, selecionando um elemento de cada nível. Por exemplo, se um segmento no eixo X (as colunas na parte superior) contém um nível com cinco elementos e um segundo nível com dois elementos, o segmento resultará em dez colunas separadas, representando todas as combinações possíveis dos elementos no os níveis. Você não pode colocar um tipo de elemento em vários eixos. Por exemplo, se você colocar o tipo de elemento de conta em linhas, não poderá adicionar contas em colunas ou filtros.
Um nível pode ter elementos individuais ou consolidados. Elementos de consolidação consolidam de forma arbitrária todos os elementos especificados neles. Elementos de consolidação não são permitidos no filtro.
O eixo do filtro se comporta de forma muito semelhante aos eixos X e Y, mas tem uma pequena diferença: como o eixo do filtro se aplica a todos os dados no relatório, ele não pode combinar seus níveis para formar várias linhas ou colunas. Em vez disso, o eixo do filtro combina todos os elementos de cada nível, agregando os dados de todos os elementos como se esses elementos estivessem sendo consolidados em uma única agregação.
Consulte Criar relatórios de matriz básicos para obter mais informações sobre segmentos, eixos e elementos de dimensão.
Exemplos de eixo de filtro
O exemplo a seguir mostra todos os elementos possíveis para o eixo do filtro.
<axis type="FILTER"> <segment> <!-- Account filter --> <tier type="acct"> <el id="258" /> </tier> <!-- Time filter --> <tier type="time"> <el id="342" /> </tier> <!-- Level filter --> <tier type="lvl"> <el id="354" /> </tier> <!-- Version filter --> <tier type="ver"> <el id="385" offset="1" offset-strata="2"/> </tier> <!-- Currency filter --> <tier type="cur"> <el id="448" /> </tier> <!-- Account Attribute filter --> <tier entity-id="23" type="aAttr"> <el id="512" /> </tier> <!-- Level Attribute filter --> <tier entity-id="25" type="lAttr"> <el id="607" /> </tier> <!-- Dimension Attribute filter --> <tier entity-id="21" type="dAttr"> <el id="649" /> </tier> <!-- Dimension filter --> <tier entity-id="1" type="dim"> <el id="717" /> </tier> </segment> </axis>
Formato da solicitação
O esquema XML para a solicitação pode ser encontrado aqui: customReportValues Especificação de REST.
<?xml version='1.0' encoding='UTF-8'?> <call method="customReportValues" callerName="a string that identifies your client application"> <credentials login="sampleuser@company.com" password="my_pwd" locale="fr_FR" instanceCode="INSTANCE1"></credentials> <requestInfo> <!-- Add elements here that we want to show up in the ELK logs --> </requestInfo> <report suppress-zeroes="1" include-element-code="1"> <!-- Run report suppressing blanks, but not zero values. Add calc element codes to the response --> <!-- columns --> <axis type="X"> <segment> <!-- time columns --> <tier type="time"> <!-- Timespan creates multiple time columns from Jan-2014 to Dec-2014.Ids specified in timespan element are retrieved from exportTime API output. 'show-time' is a mandatory attribute specifying list of strata ids --> <el complex-type="timespan" end="179001" start="168001" show-time="3,2,1"/> <el id="180001" /> <!-- single column of Jan 2015 . This id is retrieved from exportTime API output--> <subtotal code="Subtotal" /> <!-- subtotal of the output of all the time elements left of this subtotal element --> </tier> </segment> </axis> <!-- rows --> <axis type="Y"> <segment> <!-- There are 2 tiers with 2 elements and 4 elements, respectively. Without considering expansion, this generates 8 rows of: 1. dimension value with id 135, account with id 51 2. dimension value with id 135, account with id 53 3. dimension value with id 135, difference between account with id 51 and account with id 53 4. dimension value with id 135, calculation using the formula - Sum of account with id 51 and the output of the difference element from previous row 5. dimension value with id 199, account with id 51 6. dimension value with id 199, account with id 53 7. dimension value with id 199, difference between account with id 51 and account with id 53 8. dimension value with id 199, calculation using the formula - Sum of account with id 51 and the output of the difference element from previous row. Assume dimension value 135 has child 150, which has children 160,161,162. Dimension value 199 has child 200, which has children 210,211,212. With expansion, element of dimension value 135 with rollup-mode 'D' and 'suppress-elt-rollup' would yield to {135,160,161,162}. Element of dimension value 199 with 'rollup-mode' 'X' and 'start-expanded' 199,200 would yield to {199,200,210,211,212}. In total, there will be 9 x 4 = 36 rows in cartesian without suppress zero. --> - <tier entity-id="13" type="dim"> <!-- dimension values with id 135 and 199 from dimension with id of 13 --> <el id="135" rollup-mode="D" suppress-elt-rollup="1"/> <!-- Expand to Leaves operation on tag dimension id=135, return "Leaves + root" --> <el id="199" rollup-mode="X" start-expanded="199,200"/> <!-- Custom expansion with start expanded on tag dimension id=199 and 200, where 200 is a child of 199, return 199 and the the immediate children of 199 and 200 --> </tier> <tier type="acct"> <!-- account with id of 51 and 53 --> <el id="51" /> <el id="53" /> <diff operand-a="51" operand-b="53" code="Difference" /> <!-- difference between account with id 51 and account with id 53 --> <calc formula="[51]+RPT.Difference" /> <!-- calculation using the formula - Sum of account with id 51 and the output of the difference element (previous element) --> </tier> </segment> </axis> </report> </call>
Cada invocação desta chamada de API deve conter exatamente um elemento de cada um dos tipos listados:
credenciais
relatório
elemento de credenciais
| |||
Nome da etiqueta
| credenciais | ||
Descrição
| Todas as chamadas de API devem conter um único elemento de credenciais para identificar o usuário que invoca a API. A chamada à API é então executada como este usuário (qualquer trilha de auditoria ou histórico de ações no sistema mostrará que este usuário executou a ação) e, portanto, o usuário deve ter as permissões necessárias para executar a ação para que a chamada à API funcione. bem-sucedido. | ||
Atributos do elemento
| |||
Nome do atributo
| Obrigatório?
| Valor
| Exemplo
|
conectar-se | S | O nome de logon do usuário que invoca o método de API. Este usuário deve ter as permissões necessárias para invocar o método | sampleuser@company.com |
senha | S | A senha do usuário que invoca o método de API. | my_password |
parâmetros regionais | N | Especifique os parâmetros regionais a serem usados para interpretar números e datas de entrada e para formatar números e datas de saída (usando o separador de milhares, nomes de meses e formatação de data adequados). Os parâmetros regionais também são usados para especificar o idioma em que as mensagens do sistema na resposta devem ser exibidas. Se não especificado, en_US (inglês americano) é usado. | fr_FR |
instanceCode | N | Se o usuário especificado nas credenciais tem acesso a mais de uma instância do Adaptive Planning , esse atributo pode ser usado para especificar que o usuário pretende acessar uma instância diferente da instância por padrão. Se não for especificada, a instância por padrão do usuário será usada. Para determinar os códigos de instância disponíveis, use a API exportInstances. | MYINSTANCE1 |
Conteúdo do elemento
| |||
(nenhum) | |||
elemento de relatório
| |||||||||||
Nome da etiqueta
| relatório | ||||||||||
Descrição
| Especifica os elementos que compõem o relatório. | ||||||||||
Atributos do elemento
| |||||||||||
Nome do atributo
| Obrigatório?
| Valor
| Exemplo
| ||||||||
suprimir zeros
Atualizado na API v37. | N | Esse atributo controla a supressão no nível da linha. Especificar isso controlará se a saída contém zero ou linhas em branco. Os valores válidos são 0 (não suprimir nada - mostrar todas as linhas), 1 (suprimir linhas em branco - suprimir linhas que contêm apenas células em branco) e 2 (suprimir linhas em branco e zero - suprimir linhas que contêm apenas células em branco ou zero). Se esse atributo não é especificado, o valor por padrão é 2. Uma célula é considerada em branco se o valor do explorador de células para essa célula está vazio. Esse atributo funciona em conjunto com o atributo "cell-inclusions". Consulte "Células-inclusões" para verificar o comportamento por padrão. | 0 | ||||||||
cells-inclusions
Disponível na API v37. | N | Esse atributo controla a supressão no nível de célula para todas as linhas não suprimidas, conforme determinado pelo atributo "suppress-zeroes". Especificar isso controlará se a saída contém zero ou células em branco. Os valores válidos são 0 (Incluir tudo - mostra todas as células), 1 (Incluir dados e zero - Excluir células em branco) e 2 (Incluir somente dados - Excluir zero e células em branco). Comportamento por padrão: se esse atributo não é especificado, o comportamento por padrão é ditado pelo atributo "suppress-zeroes". Comportamento para diferentes valores de atributo "suppress-zeroes":
| 0 | ||||||||
show-cell-notes | N | Quando fornecido, esse atributo mostra ou oculta as observações da célula. 0 = não mostrar observações de célula (valor por padrão), 1 = mostrar observações de célula | 1 | ||||||||
suprimir consolidações | N | Quando fornecido, esse atributo mostra ou oculta linhas e colunas de consolidação. As linhas e colunas de consolidação são suprimidas apenas para os pais cujos filhos estão presentes no relatório. Os valores válidos são 0 (Não suprimir consolidações) ou 1 (Suprimir consolidações). O valor por padrão é 0. | 1 | ||||||||
include-element-code | N | Quando fornecido, esse atributo adiciona ou oculta os códigos dos elementos Calc (Subtotal, Diferença e Cálculo). Os valores válidos são 0 (não adicionar códigos à saída de elementos de cálculo) ou 1 (adicionar códigos à saída de elementos de cálculo). O valor por padrão é 0. | 1 | ||||||||
Conteúdo do elemento
| |||||||||||
Consulte o Formato da solicitação para obter mais detalhes. | |||||||||||
Formato da resposta
O esquema XML para a resposta pode ser encontrado em customReportValues Especificação de REST.
<?xml version="1.0" encoding="utf-8"?> <response success="true"> <messages> <!-- Dimension value id 13 is invalid. Rows with value id 13 has been removed from the report. --> <message type="WARNING" key="invalid-dim-attr-id" values="199,13">Invalid value Id 199 for dimension/attribute type id 13 </message> </messages> <!-- Global filters. Although the request did not supply any filters, defaults are used when dimension types are not specified. Reporting against version with id 2 which is the current version. Level with id 1 is the top most level this user has access to. --> <filters> <coords> <coord type="ver" rollup="1"> <el id="2" /> </coord> <coord type="lvl" rollup="1"> <el id="1" /> </coord> </coords> </filters> <!-- Only two time columns Dec-2014 and Jan-2015 have data, all other columns have been removed --> <cols> <col id="1"> <coords> <coord type="time"> <el id="179001" /> </coord> </coords> </col> <col id="2"> <coords> <coord type="time"> <el id="180001" /> </coord> </coords> </col> <col id="3"> <coords> <coord code="Subtotal" type="subtotal" /> </coords> </col> </cols> <rows> <row> <!-- Row coordinates are account with id 51 and dimension value with id of 135 from dimension with id of 13 --> <coords> <coord type="acct"> <el id="51" /> </coord> <coord type="dim" entity-id="13"> <el id="135" /> </coord> </coords> <cell value="2.345" col="1" /> <!-- This value’s coordinates are the row coordinates listed above, matches column position 1 and the global filters. --> <cell value="2.345" col="2" /> <!-- This value’s coordinates are the row coordinates listed above, matches column position 2 and the global filters. --> <cell value="4.69" col="3" /> <!-- This value’s coordinates are the row coordinates listed above, matches column position 2 and the global filters. --> </row> <row> <!-- Row coordinates are account with id 53 and dimension value with id of 135 from dimension with id of 13 --> <coords> <coord type="acct"> <el id="53" /> </coord> <coord type="dim" entity-id="13"> <el id="135" /> </coord> </coords> <cell value="5.34" col="1" /> <!-- This value’s coordinates are the row coordinates listed above, matches column position 1 and the global filters. --> <cell value="7.44" col="2" /> <!-- This value’s coordinates are the row coordinates listed above, matches column position 2 and the global filters. --> <cell value="12.78" col="3" /> <!-- This value’s coordinates are the row coordinates listed above, matches column position 2 and the global filters. --> </row> <row> <coords> <coord code="Difference" type="diff" /> <coord type="dim" entity-id="13"> <el id="135" /> </coord> </coords> <cell value="2.995" col="1" /> <cell value="5.095" col="2" /> <cell value="8.09" col="3" /> </row> <row> <coords> <coord type="calc" /> <coord type="dim" entity-id="13"> <el id="135" /> </coord> </coords> <cell value="5.34" col="1" /> <cell value="7.44" col="2" /> <cell value="12.78" col="3" /> </row> </rows> </report> </output> </response>
elemento de resposta
| |||
Nome da etiqueta
| resposta | ||
Atributos do elemento
| |||
Nome do atributo
| Obrigatório?
| Valor
| Exemplo
|
êxito | S | Verdadeiro ou falso, indicando se a chamada à API foi bem-sucedida ou não. Mesmo as chamadas bem-sucedidas podem conter mensagens de aviso na resposta. | verdadeiro |
obsoleto | N | Se presente na etiqueta de resposta e definido como verdadeiro, esse atributo indica que a versão do método ou da API que está sendo invocada se tornou obsoleta e está oficialmente obsoleta. Embora continue a funcionar neste momento, pode deixar de funcionar em breve. Normalmente, esse atributo não está presente. | false |
Conteúdo do elemento
| |||
Um único elemento de mensagens opcional e exatamente um elemento de saída obrigatório. | |||
elemento de mensagens
| |
Nome da etiqueta
| mensagens |
Descrição
| Contêiner para um ou mais elementos de mensagem. |
Atributos do elemento
| |
(nenhum) | |
Conteúdo do elemento
| |
Um ou mais elementos de mensagem. | |
elemento de mensagem
| |||
Nome da etiqueta
| mensagem | ||
Descrição
| Representa uma mensagem que está sendo enviada pelo sistema de volta para o autor da chamada. As mensagens são usadas para mensagens de erro quando as solicitações não são bem-sucedidas, para mensagens de aviso quando as solicitações são bem-sucedidas e para mensagens de confirmação quando as solicitações são bem-sucedidas. | ||
Atributos do elemento
| |||
Nome do atributo
| Obrigatório ? | Valor
| Exemplo
|
type | S | O tipo é uma maneira de identificar o tipo de mensagem. Os diferentes tipos são INFORMAÇÃO, AVISO e ERRO. O tipo "ERROR" significa que esta solicitação não foi processada. | AVISO |
chave | S | Uma chave é uma maneira de identificar uma determinada mensagem ou tipo de mensagem, útil para fins de registro e recuperação automatizados de erros em programas cliente. As chaves não são alteradas em diferentes parâmetros regionais de solicitações, mesmo quando o idioma da mensagem é alterado. As chaves também não devem ser alteradas no futuro devido a ajustes de texto ou alterações de terminologia. | warning-invalid-time-span-start |
valores | N | Quando fornecidos, os valores representam variáveis que são usadas no texto da mensagem. | 199,12 |
Conteúdo do elemento
| |||
O texto da mensagem. Esse texto está no idioma dos parâmetros regionais especificados na solicitação (supondo que haja suporte para os parâmetros regionais). O texto também pode conter informações variáveis, como o número de linhas que foram processadas ou a coluna ou valor específico que causou um erro. | |||
elemento de saída
| |
Nome da etiqueta
| saída |
Descrição
| |
Atributos do elemento
| |
(nenhum) | |
Conteúdo do elemento
| |
Consulte o XML da resposta para obter mais detalhes. | |