Esta é a documentação do Apigee Edge.
Acesse
Documentação da Apigee X. informações
Introdução
Os relatórios de monetização permitem que você acesse informações de uso e atividade de transações focadas. Por exemplo, é possível determinar quais aplicativos, desenvolvedores, pacotes de produtos de API ou produtos de API atividade de transação específica para um determinado período. Com a monetização, é possível gerar um resumo ou relatórios detalhados que acompanham o uso da API.
Tipos de relatórios de monetização
Você pode gerar os seguintes tipos de relatório de monetização.
| Denunciar | Descrição |
|---|---|
| Faturamento | Conferir a atividade dos desenvolvedores em um único mês de faturamento e verificar se a taxa planos foram aplicados corretamente. |
| Saldo pré-pago | Confira os preenchimentos de saldo que um desenvolvedor pré-pago fez em um mês de faturamento ou em um mês em aberto, para que você possa reconciliar com os pagamentos recebidos do seu um processador de pagamentos. |
| Receita | Confira a atividade e a receita gerada por desenvolvedores em um período. analisar o desempenho dos seus produtos e pacotes de produtos de API entre os desenvolvedores (e os aplicativos conteinerizados). |
| Variância |
Compare a atividade e a receita gerada por desenvolvedores em dois períodos, para que você pode analisar tendências para cima ou para baixo no desempenho de seus pacotes e produtos de API entre os desenvolvedores (e os aplicativos deles). |
Sobre a retenção de dados
Na nuvem pública do Apigee Edge, a retenção de dados de monetização é um direito do plano. Consulte a direitos de monetização em https://cloud.google.com/apigee/specsheets. Entre em contato com a equipe de vendas da Apigee se você quiser que os dados de monetização sejam retidos além do direito. período A retenção estendida de dados é ativada no momento da solicitação e não pode ser ativada de modo retroativo para incluir dados anteriores à janela original de retenção de dados.
Sobre transações duplicadas
Se você comparar os relatórios de transações de monetização com os dados do Analytics, notará uma pequena o número de transações duplicadas. Esse é o comportamento esperado, já que o sistema de monetização processar vários milhões de transações diariamente, com muitas transações processadas em paralelo a qualquer em um determinado momento. Em média, cerca de 0,1% das transações podem ser duplicadas.
Como explorar a página "Relatórios de monetização"
Acesse a página "Relatórios de monetização", conforme descrito abaixo.
Edge
Para acessar a página "Relatórios" usando a interface do Edge:
- Faça login em apigee.com/edge.
- Selecione Publicar > Monetização > Relatórios na barra de navegação à esquerda.
A página "Relatórios" é exibida.
Como destacado na figura, a página "Relatórios" permite:
- acessar informações resumidas de todos os relatórios, incluindo nome e descrição, tipo de relatório, período e data da última modificação;
- Configurar um relatório
- Gere e faça o download de um relatório no formato de arquivo CSV ou ZIP.
- Editar um relatório
- Excluir um relatório
- Pesquisar na lista de relatórios
Edge clássico (nuvem privada)
Para acessar a página "Relatórios" usando a interface clássica do Edge:
- Faça login em
http://ms-ip:9000, em que ms-ip é o endereço IP ou o nome DNS do nó do servidor de gerenciamento. - Selecione Monetização > Relatórios de monetização na barra de navegação superior.
A página "Relatórios" é exibida.
- Ver a lista atual de relatórios
- Configurar um relatório
- Gere e faça o download de um relatório no formato CSV.
- Editar um relatório
- Excluir um relatório
Como configurar um relatório
Configure um relatório usando a IU, conforme descrito nas seções a seguir.
Etapas para configurar um relatório
Configure um relatório usando a interface do Edge ou a interface do Classice Edge.
Edge
Para configurar um relatório usando a interface do Edge:
- Selecione Publicar > Monetização > Relatórios na barra de navegação à esquerda.
- Clique em + Relatório.
- Configure os detalhes do relatório definidos na tabela a seguir.
Campo Descrição Nome Nome exclusivo do relatório. Descrição Descrição do relatório. Tipo de relatório Consulte Tipos de relatório de monetização. - Configure os outros detalhes do relatório com base no tipo selecionado, conforme descrito nas seguintes seções:
- Depois de inserir as informações na janela de relatórios, você poderá:
- Clique em Salvar relatório para salvar a configuração do relatório.
Somente para um relatório detalhado, clique em Enviar job para gerar o relatório de forma assíncrona. e recuperar os resultados posteriormente. Consulte Como gerar e fazer o download de um relatório para mais informações.
- Clique em Salvar como CSV ou Salvar como ZIP para fazer o download do relatório gerado para sua máquina local como um valores separados por vírgula (CSV) ou um arquivo ZIP compactado contendo o CSV. Os downloads de arquivos ZIP são recomendados para relatórios grandes e o download será mais eficaz.
Edge clássico (nuvem privada)
Para criar um relatório usando a interface clássica do Edge:
- Selecione Monetização > Relatórios de monetização na barra de navegação superior.
- No menu suspenso, selecione o tipo de relatório que você quer criar. Consulte Tipos de relatório de monetização.
- Clique em + Relatório.
- Configure os detalhes do relatório com base no tipo de faturamento selecionado, conforme descrito nas seguintes seções:
- Depois de inserir as informações na janela de relatórios, você poderá:
- Clique em Salvar como ... para salvar a configuração do relatório e fazer o download dele mais tarde.
Apenas para um relatório detalhado, clique em Enviar job para gerar o relatório de forma assíncrona. e recuperar os resultados posteriormente. Consulte Como gerar e fazer o download de um relatório para mais informações.
- Clique em Fazer download do CSV para gerar o relatório e fazer o download dele para sua máquina local como um arquivo de valores separados por vírgula (CSV) para visualização.
Como configurar um relatório de faturamento
Siga as etapas para configurar um relatório e insira as seguintes informações na página dele:
| Campo | Descrição |
|---|---|
| Mês de faturamento |
O mês de faturamento do relatório. |
| Nível do relatório |
Nível do relatório. Valores válidos:
|
| Pacotes de produtos |
Observação: na interface clássica do Edge, os pacotes de produtos de API são chamados de pacotes de API. Selecione os pacotes de produtos de API a serem incluídos no relatório. Se nenhum pacote for selecionado, todos os pacotes de produtos de API serão incluídos no no relatório. O relatório inclui uma linha separada para cada pacote de produtos de API selecionados. Para um relatório de resumo, você pode marcar Não exibir nas opções de exibição "Resumo". Nesse caso, o relatório agrega informações em todos os pacotes de produtos de API (ou selecionados) e não lista informações para cada pacote de produto da API separadamente). |
| Produtos |
Selecione os produtos de API a serem incluídos no relatório. Se nenhum for selecionado, todos os produtos de API serão incluídos na no relatório. O relatório inclui uma linha separada para cada produto de API selecionado. Para um relatório de resumo, você pode marcar Não exibir nas opções de exibição "Resumo". Nesse caso, o relatório agrega informações de todos os desenvolvedores (ou selecionados) e não lista informações para cada desenvolvedor selecionado separadamente). |
| Empresas | Selecione as empresas a serem incluídas no relatório. Se nenhuma for selecionada, todas as empresas serão incluídas na no relatório. |
| Plano de tarifas |
Os planos de tarifas a serem incluídos no relatório. Selecione uma das seguintes opções:
|
Como configurar um relatório de saldo pré-pago
Siga as etapas para configurar um relatório e insira as seguintes informações na página dele:| Campo | Descrição |
|---|---|
| Mês de faturamento |
O mês de faturamento do relatório. |
| Nível do relatório |
Nível do relatório. Valores válidos:
|
| Empresas | Selecione as empresas a serem incluídas no relatório. Se nenhuma for selecionada, todas as empresas serão incluídas na no relatório. |
Como configurar um relatório de receita
Siga as etapas para configurar um relatório e insira as seguintes informações na página dele:
| Campo | Descrição |
|---|---|
| Período |
Período do relatório. Selecione uma das seguintes opções:
|
| Selecionar moeda |
Moeda do relatório. Valores válidos:
|
| Nível do relatório |
Nível do relatório. Valores válidos:
|
| Pacotes de produtos |
Observação: na interface clássica do Edge, os pacotes de produtos de API são chamados de pacotes de API. Selecione os pacotes de produtos de API a serem incluídos no relatório. Se nenhum pacote for selecionado, todos os pacotes de produtos de API serão incluídos no no relatório. O relatório inclui uma linha separada para cada pacote de produtos de API selecionados. Para um relatório de resumo, você pode marcar Não exibir nas opções de exibição "Resumo". Nesse caso, o relatório agrega informações em todos os pacotes de produtos de API (ou selecionados) e não lista informações para cada pacote de produto da API separadamente). |
| Produtos |
Selecione os produtos de API a serem incluídos no relatório. Se nenhum for selecionado, todos os produtos de API serão incluídos na no relatório. O relatório inclui uma linha separada para cada produto de API selecionado. Para um relatório de resumo, você pode marcar Não exibir nas opções de exibição "Resumo". Nesse caso, o relatório agrega informações de todos os desenvolvedores (ou selecionados) e não lista informações para cada desenvolvedor selecionado separadamente). |
| Empresas | Selecione as empresas a serem incluídas no relatório. Se nenhuma for selecionada, todas as empresas serão incluídas na no relatório. Para um relatório de resumo, você pode marcar Não exibir no Seção Resumo de opções de exibição. Nesse caso, o relatório agrega informações de todas as empresas (ou selecionadas) (ele não lista informações de cada empresa selecionada separadamente). |
| Apps |
Selecione os aplicativos incluir no relatório. Se nenhum for selecionado, todos os aplicativos serão incluídos no relatório. O relatório inclui uma linha separada para cada aplicativo selecionado. Para um relatório de resumo, você pode marcar Não exibir no Seção Resumo de opções de exibição. Nesse caso, o relatório agrega informações todos os aplicativos (ou selecionados) e não lista as informações de cada um o aplicativo separadamente). |
| Opções de exibição do resumo |
Ordem em que as colunas são agrupadas e exibidas no relatório. Selecione um número que indica a ordem relativa dessa seção no agrupamento (1 é a primeira do grupo. Por exemplo, os seguintes grupos agrupam o relatório primeiro por pacotes e depois por produtos, por desenvolvedores e, em seguida, por aplicativos.
Se você não quiser exibir uma seção, selecione Não exibir e, em seguida, selecione os campos restantes em ordem. O pedido é atualizado automaticamente quando você altera o ordem relativa de uma seção ou optam por não exibir uma seção no relatório. |
Incluir atributos personalizados de transação em relatórios de resumo da receita
As políticas de registro de transações permitem capturar dados de atributos personalizados das transações.
inclua esses atributos personalizados nos relatórios resumidos de receita. Defina o conjunto padrão de
atributos personalizados incluídos nas tabelas do banco de dados de monetização definindo
a propriedade MINT.SUMMARY_CUSTOM_ATTRIBUTES da organização.
Para usar esse recurso, é necessário pensar e planejar um pouco. Analise as considerações abaixo.
Se você é um cliente de nuvem, entre em contato com o suporte do Apigee Edge para definir o . Se você for cliente do Apigee Edge para nuvem privada, defina a sinalização usando uma solicitação PUT para a seguinte API com credenciais de administrador do sistema.
curl -u email:password -X PUT -H "Content-type:application/xml" http://host:port/v1/o/{myorg} -d \ "<Organization type="trial" name="MyOrganization"> <Properties> <Property name="features.isMonetizationEnabled">true</Property> <Property name="MINT.SUMMARY_CUSTOM_ATTRIBUTES">["partner_id","tax_source"]</Property> <Property name="features.topLevelDevelopersAreCompanies">false</Property> </Properties> </Organization>"
Neste exemplo, a chamada de API ativa o recurso e
adiciona as colunas partner_id e tax_source ao
no banco de dados de monetização. A matriz de atributos personalizados na chamada de API é
Codificado para URL.
Considerações para incluir atributos de transação personalizados em relatórios
- Confirme os nomes dos atributos que você quer usar antes de criá-los com a API. Esses são os nomes das colunas no banco de dados, e os dados de atributos personalizados são sempre armazenados lá.
- Há 10 slots de atributos personalizados disponíveis em cada política de registro de transação, conforme
como mostrado na imagem a seguir. Use exatamente os mesmos nomes e posições de atributos para os mesmos
atributos nos produtos que serão incluídos nos relatórios. Por exemplo, no seguinte
política de gravação de transações, os atributos
partner_idetax_sourcepersonalizados os atributos ocupam as caixas 4 e 5, respectivamente. Deve ser o nome e a posição dele em todos políticas de registro de transações dos produtos que serão incluídos nos relatórios.
Para incluir atributos personalizados em um relatório de resumo da receita após ativar o recurso, use o método
da API de relatórios adicionando transactionCustomAttributes
o MintCriteria. Consulte Configuração de critérios
.
Como configurar um relatório de variações (descontinuado)
Siga as etapas para configurar um relatório e insira as seguintes informações na página dele:
| Campo | Descrição |
|---|---|
| Período |
Período do relatório. Selecione uma das seguintes opções:
|
| Pacotes |
Os pacotes de API a serem incluídos no relatório. Selecione uma das seguintes opções:
O relatório inclui uma linha separada para cada pacote de API selecionado. Para um relatório de resumo, você pode marcar "Não exibir (pacotes)" na seção "Resumo" Seção "Opções de exibição". Nesse caso, o relatório agrega informações de todos (ou selecionados) pacotes de API (e não lista informações para cada pacote de API) separadamente). |
| Produtos |
Os produtos de API a serem incluídos no relatório. Selecione uma das seguintes opções:
O relatório inclui uma linha separada para cada produto de API selecionado. Para um relatório de resumo, você pode marcar Não exibir (produtos) na seção "Resumo" Seção "Opções de exibição". Nesse caso, o relatório agrega informações de todos (ou selecionados) produtos de API (e não lista informações para cada produto de API separadamente). |
| Empresas |
São as empresas a serem incluídas no relatório. Selecione uma das seguintes opções:
O relatório inclui uma linha separada para cada empresa selecionada. Para um relatório de resumo, você pode marcar Não exibir (empresas) no campo Seção Resumo de opções de exibição. Nesse caso, o relatório agrega informações todas (ou as empresas selecionadas) (e não lista informações de cada empresa selecionada) separadamente). |
| Apps |
Os aplicativos a serem incluídos no relatório. Selecione uma das seguintes opções:
O relatório inclui uma linha separada para cada aplicativo selecionado. Para obter um relatório de resumo, você pode marcar Não exibir (Aplicativos) no campo Seção Resumo de opções de exibição. Nesse caso, o relatório agrega informações todos os aplicativos (ou selecionados) e não lista as informações de cada um o aplicativo separadamente). |
| Moeda |
Moeda do relatório. Valores válidos:
|
| Opções de exibição do resumo |
Ordem em que as colunas são agrupadas e exibidas no relatório. Selecione um número que indica a ordem relativa dessa seção no agrupamento (1 é a primeira do grupo. Por exemplo, os seguintes grupos agrupam o relatório primeiro por pacotes e depois por produtos, por desenvolvedores e, em seguida, por aplicativos.
Se você não quiser exibir uma seção, selecione Não exibir e, em seguida, selecione os campos restantes em ordem. O pedido é atualizado automaticamente quando você altera o ordem relativa de uma seção ou optam por não exibir uma seção no relatório. |
Como gerar e fazer o download de um relatório
Depois de criar um relatório, você poderá fazer o download dos resultados no formato de arquivo CSV ou ZIP. É possível gerar o arquivo CSV ou ZIP de maneira síncrona ou assíncrona.
Para um relatório síncrono, você executa a solicitação de relatório, e a solicitação fica bloqueada até o servidor de análise retornar uma resposta. No entanto, como um relatório pode precisar processar uma grande quantidade de dados (por exemplo, centenas de GB), um relatório síncrono pode expirar.
O nível de relatório Resumo só é compatível com a geração síncrona.
Para um relatório assíncrono, você executa a solicitação de relatório e recupera os resultados posteriormente. Veja a seguir algumas situações em que o processamento de consulta assíncrona pode ser uma boa alternativa:
- Análise e criação de relatórios que abrangem períodos longos
- Análise de dados com uma variedade de dimensões de agrupamento e outras restrições que aumentam a complexidade da consulta
- Gerenciamento de consultas quando você perceber que os volumes de dados aumentaram significativamente para alguns usuários ou organizações
O nível de relatório Detalhado é compatível com a geração assíncrona.
Para gerar e fazer o download de um relatório no formato de arquivo CSV ou zip, execute uma das seguintes tarefas:
- Acesse a página "Relatórios".
- Posicione o cursor sobre o relatório que você quer transferir por download.
Na coluna Modificado, clique em:
- O
ou o 
(para um relatório de resumo). O relatório é salvo de forma síncrona como um arquivo CSV ou ZIP. - Enviar job (para um relatório detalhado). O job assíncrono é iniciado.
Monitore o status do job na coluna Modificado.
O ícone de disco aparece quando o relatório está pronto para download:
- Após a conclusão do job, clique no ícone de disco para fazer o download do relatório.
- O
Veja a seguir um exemplo de arquivo CSV para um relatório de faturamento resumido.
Como editar um relatório
Para editar um relatório:
- Acesse a página "Relatórios".
- Posicione o cursor sobre o relatório que você quer editar e clique em
no menu de ações. - Atualize a configuração do relatório conforme necessário.
- Clique em Atualizar relatório para salvar a configuração atualizada do relatório.
Como excluir um relatório
Para excluir um relatório:
- Acesse a página "Relatórios".
- Posicione o cursor sobre o relatório que você quer excluir.
- Clique em
no menu de ações.
Como gerenciar relatórios de monetização usando a API
As seções a seguir descrevem como gerenciar relatórios de monetização usando a API.
Como configurar um relatório usando a API
Para configurar um relatório para uma organização inteira, envie uma solicitação POST para
/organizations/{org_name}/report-definitions:
Para configurar um relatório para um desenvolvedor específico, envie uma solicitação POST para
/organizations/{org_name}/developers/{dev_id}/report-definitions, em que
{dev_id} é a identificação do desenvolvedor.
Ao fazer a solicitação, é necessário especificar o nome e o tipo do relatório. O tipo é
uma das seguintes opções: BILLING, REVENUE, VARIANCE (descontinuado) ou
PREPAID_BALANCE. Além disso, é possível especificar critérios no
mintCriteria que configura o relatório ainda mais. Há uma ampla variedade de
que podem ser especificados. Isso oferece muita flexibilidade na configuração do relatório.
Você pode especificar alguns itens como critérios:
- Em um relatório de faturamento ou de saldo pré-pago, o mês de faturamento do relatório
- Em um relatório de receita, o tipo de transações cobertas no relatório, como compras transações, transações de cobrança e reembolsos
- Em um relatório de saldo pré-pago, o desenvolvedor a quem ele se aplica
- Para um relatório de receita, os pacotes de produtos de API (ou pacotes de API), produtos, planos de preços e aplicativos aos quais o relatório aplicável
- Para um relatório de receita ou variação, a moeda aplicável do relatório.
- Nos relatórios de faturamento, de saldo pré-pago ou de receita, seja um resumo ou um relatório detalhado
- Para um relatório de resumo da receita, inclua atributos personalizados de transação.
Consulte Opções de configuração de relatórios para uma lista completa das critérios do relatório.
Por exemplo, o código a seguir cria um relatório de receita que resume a atividade de transação para
no mês de julho de 2015. O relatório inclui vários tipos de transação especificados
transactionTypes e se aplica especificamente ao pacote de produtos da API Payment e
Produto da API Payment. Como nenhum desenvolvedor ou aplicativo específico foi especificado no relatório
definição, o relatório se aplica a todos os desenvolvedores e aplicativos. E, como o
currencyOption é definida como LOCAL, cada linha do relatório
serão mostrados usando a moeda do plano de tarifação aplicável. Além disso,
groupBy especifica que as colunas do relatório serão agrupadas no
a seguinte ordem: PACKAGE, PRODUTO, DESENVOLVEDOR, APLICATIVO e RATEPLAN (inclui o nome do plano de tarifação)
e ID no relatório).
$ curl -H "Content-Type: application/json" -X POST -d \
'{
"name": "July 2015 revenue report",
"description": " July 2015 revenue report for Payment product",
"type": "REVENUE",
"mintCriteria":{
"fromDate":"2015-07-01 00:00:00",
"toDate":"2015-08-01 13:35:00",
"showTxDetail":true,
"showSummary":true,
"transactionTypes":[
"PURCHASE",
"CHARGE",
"REFUND",
"CREDIT",
"SETUPFEES",
"TERMINATIONFEES",
"RECURRINGFEES"
],
"monetizationPackageIds":[
"payment"
],
"productIds":[
"payment"
],
"currencyOption":"LOCAL",
"groupBy":[
"PACKAGE",
"PRODUCT",
"DEVELOPER",
"APPLICATION",
"RATEPLAN"
]
}
}' \
"https://api.enterprise.apigee.com/v1/mint/organizations/{org_name}/report-definitions" \
-u email:password
O código a seguir cria um relatório de faturamento detalhado que mostra a atividade de um desenvolvedor DEV FIVE para junho de 2015.
$ curl -H "Content-Type:application/json" -X POST -d \
'{
"name": "June billing report, DEV FIVE",
"description": "June billing report, DEV FIVE",
"type": "BILLING",
"mintCriteria":{
"billingMonth": "JUNE",
"billingYear": 2015,
"showTxDetail":true,
"showSummary":false,
"currencyOption":"LOCAL"
},
"devCriteria":[{
"id":"RtHAeZ6LtkSbEH56",
"orgId":"myorg"}]
}' \
"https://api.enterprise.apigee.com/v1/mint/organizations/{org_name}/developers/5cTWgdUvdr6JW3xU/report-definitions" \
-u email:password
Visualizar as configurações de relatórios usando a API
É possível consultar uma configuração de relatório específica ou todas as configurações de uma organização. Você também podem visualizar as configurações de relatório de um desenvolvedor individual.
Para visualizar uma configuração de relatório específica para uma organização, envie uma solicitação GET para
/organizations/{org_name}/report-definitions/{report_definition_id}, em que
{report_definition_id} é a identificação da configuração específica do relatório (o
ID é retornado na resposta quando você cria a configuração do relatório). Exemplo:
$ curl -H "Accept:application/json" -X GET \
"https://api.enterprise.apigee.com/v1/mint/organizations/{org_name}/report-definitions/1f7fa53b-de5a-431d-9438-62131e1396c5" \
-u email:password
Para visualizar todas as configurações de relatório da organização, envie uma solicitação GET para
/organizations/{org_name}/report-definitions:
Transmita os seguintes parâmetros de consulta para filtrar e classificar os resultados:
| Parâmetro de consulta | Descrição |
|---|---|
all |
Sinalização que especifica se todos os pacotes de produtos da API precisam ser retornados. Se definido como false, o número de pacotes de produtos da API retornados por página será
definida pelo parâmetro de consulta size. O padrão é false. |
size |
Número de pacotes de produtos da API retornados por página. O padrão é 20. Se a consulta all
for definido como true, ele será ignorado. |
page |
Número da página que você quer retornar (se o conteúdo for paginado). Se
o parâmetro de consulta all for definido como true, essa
será ignorado. |
sort |
Campo que classifica as informações. Se a consulta all
for definido como true, ele será ignorado. O valor padrão é UPDATED:DESC. |
Por exemplo, o comando a seguir retorna as configurações de relatório da organização e limita o até cinco configurações de relatório:
$ curl -H "Accept:application/json" -X GET \
"https://api.enterprise.apigee.com/v1/mint/organizations/{org_name}/report-definitions?size=5" \
-u email:password
A resposta deve ser semelhante a esta (apenas parte da resposta é exibida):
{ "reportDefinition" : [ { "description" : "Test revenue report", "developer" : null, "id" : "1f7fa53b-de5a-431d-9438-62131e1396c5", "lastModified" : "2015-08-27 15:44:03", "mintCriteria" : { "asXorg" : false, "currencyOption" : "LOCAL", "fromDate" : "2015-07-01 00:00:00", "groupBy" : [ "PACKAGE", "PRODUCT", "DEVELOPER", "APPLICATION", "RATEPLAN" ], "monetizationPackageIds" : [ "payment" ], "productIds" : [ "payment" ], "showRevSharePct" : false, "showSummary" : true, "showTxDetail" : true, "showTxType" : false, "toDate" : "2015-08-01 00:05:00", "transactionTypes" : [ "PURCHASE", "CHARGE", "REFUND", "CREDIT", "SETUPFEES", "TERMINATIONFEES", "RECURRINGFEES" ] }, "name" : "Test revenue report", "organization" : { ... }, "type" : "REVENUE" }, { "description" : "June billing report, DEV FIVE", "developer" : null, "id" : "fedac696-ce57-469b-b62c-a77b535fd0eb", "lastModified" : "2015-08-27 17:13:20", "mintCriteria" : { "asXorg" : false, "billingMonth" : "JUNE", "billingYear" : 2015, "currencyOption" : "LOCAL", "showRevSharePct" : false, "showSummary" : false, "showTxDetail" : true, "showTxType" : false }, "name" : "June billing report, DEV FIVE", "organization" : { ... }, "type" : "BILLING" } ], "totalRecords" : 2 }
Para visualizar as configurações de relatório de um desenvolvedor específico, envie uma solicitação GET para
/organizations/{org_name}/developers/{dev_id}/report-definitions, em que
{dev_id} é a identificação do desenvolvedor. Ao fazer a solicitação, é possível
especifique os parâmetros de consulta descritos acima para filtrar e classificar os dados.
Por exemplo, o comando a seguir retorna as configurações de relatório de um desenvolvedor específico e classifica os resposta por nome de relatório:
$ curl -H "Accept:application/json" -X GET \
"https://api.enterprise.apigee.com/v1/mint/organizations/{org_name}/developers/5cTWgdUvdr6JW3xUreport-definitions?sort=name" \
-u email:password
Como atualizar a configuração de um relatório usando a API
Para atualizar a configuração de um relatório, emita uma solicitação PUT para
/organizations/{org_name}/report-definitions/{report_definition_id}, em que
{report_definition_id} é a identificação da configuração específica do relatório. Quando
você fizer a atualização, será necessário especificar no corpo da solicitação os valores de configuração atualizados e o ID de
a configuração do relatório. Por exemplo, a solicitação a seguir atualiza o relatório para um relatório de resumo
(as propriedades atualizadas estão destacadas):
$ curl -H "Content-Type: application/json" -X PUT -d \
'{
"id": "fedac696-ce57-469b-b62c-a77b535fd0eb",
"name": "June billing report, DEV FIVE",
"description": "June billing report, DEV FIVE",
"type": "BILLING",
"mintCriteria":{
"billingMonth": "JUNE",
"billingYear": 2015,
"showTxDetail":false,
"showSummary":true
}
}' \
"https://api.enterprise.apigee.com/v1/mint/organizations/{org_name}/report-definitions/fedac696-ce57-469b-b62c-a77b535fd0eb" \
-u email:password
A resposta deve ser semelhante a esta (apenas parte da resposta é exibida):
{ "description" : "June billing report, DEV FIVE", "developer" : null, "id" : "fedac696-ce57-469b-b62c-a77b535fd0eb", "lastModified" : "2015-08-27 17:47:29", "mintCriteria" : { "asXorg" : false, "billingMonth" : "JUNE", "billingYear" : 2015, "showRevSharePct" : false, "showSummary" : true, "showTxDetail" : false, "showTxType" : false }, "name" : "June billing report, DEV FIVE", "organization" : { ... }, "type" : "BILLING" }
Excluir uma configuração de relatório usando a API
Para excluir uma configuração de relatório, emita uma solicitação DELETE para
/organizations/{org_namer}/report-definitions/{report_definition_id}, em que
{report_definition_id} é a identificação da configuração do relatório a ser excluída.
Exemplo:
$ curl -H "Accept:application/json" -X DELETE \
"https://api.enterprise.apigee.com/v1/mint/organizations/{org_name}/report-definitions/fedac696-ce57-469b-b62c-a77b535fd0eb" \
-u email:password
Como gerar um relatório usando a API
Depois de configurar um relatório, você pode gerá-lo em valores separados por vírgula (CSV) para visualização.
Para gerar um relatório, envie uma solicitação POST para
organizations/{org_id}/{report_type}, em que {report_type} especifica o
o tipo de relatório que você quer gerar. Os tipos são:
billing-reportsrevenue-reportsprepaid-balance-reportsvariance-reports
Por exemplo, para gerar um relatório de cobrança, envie uma solicitação POST para
organizations/{org_name}/billing-reports:
No corpo da solicitação (para qualquer tipo de relatório), especifique os critérios de pesquisa do relatório. Usar
mintCriteria para especificar os critérios de pesquisa. Consulte Opções de configuração de critérios para mais detalhes.
Por exemplo, a solicitação a seguir procura um relatório de receita com base em vários critérios como datas de início e término do relatório e tipos de transação.
$ curl -H "Content-Type:application/json" -H "Accept: application/octet-stream" -X POST -d \
'{
"fromDate":"2015-07-01 00:00:00",
"toDate":"2015-08-01 13:35:00",
"showTxDetail":true,
"showSummary":true,
"transactionTypes":[
"PURCHASE",
"CHARGE",
"REFUND",
"CREDIT",
"SETUPFEES",
"TERMINATIONFEES",
"RECURRINGFEES"
],
"currencyOption":"LOCAL",
"groupBy":[
"PACKAGE",
"PRODUCT",
"DEVELOPER",
"APPLICATION",
"RATEPLAN"]
}' \
"https://api.enterprise.apigee.com/v1/mint/organizations/{org_name}/revenue-reports" \
-u email:password
Se encontrado, o relatório de receita é gerado no formato de arquivo CSV. Confira a seguir exemplo de saída do relatório:
Reporting Period:,From:,2015-07-01, To:,2015-07-31 API Product:,All Developer:,All Application:,All Currency:,Local Type of Report:,Summary Revenue Report Monetization Package,Package ID,API Product,Product ID,Developer Name,Developer ID,Application Name,Application ID,Rate Plan,Plan ID,Currency,Transaction Type,Provider Status,Total Volume,Charged Rate, Location,location,foo_product,foo_product,Apigee,QQ7uxeMGf3w9W08B,my_app,my_app,rate_plan_1,location_rate_plan_1,USD,SETUPFEES,SUCCESS,1,15.0000, Location,location,foo_product,foo_product,BarCompany,barcompany,my_app,my_app,rate_plan_1,location_rate_plan_1,USD,SETUPFEES,SUCCESS,1,15.0000, Location,location,foo_product,foo_product,fremont,fremont,my_app,my_app,rate_plan_1,location_rate_plan_1,USD,SETUPFEES,SUCCESS,1,15.0000, Location,location,foo_product,foo_product,Juan's Taco Shack,juan-s-taco-sha,my_app,my_app,rate_plan_1,location_rate_plan_1,USD,SETUPFEES,SUCCESS,1,15.0000,
Incluir atributos personalizados do desenvolvedor nos relatórios de receita usando o API
Para relatórios de receita, é possível incluir atributos personalizados, é definido para o desenvolvedor. Você define atributos personalizados ao adicionar desenvolvedores sua organização, conforme descrito em Como gerenciar desenvolvedores de apps.
Para incluir atributos personalizados em um relatório de receita, envie uma solicitação POST para
organizations/{org_name}/revenue-reports e inclua o
Matriz devCustomAttributes no corpo da solicitação:
"devCustomAttributes": [
"custom_attribute1",
"custom_attribute2",
...
]Observação:não especifique os MINT_* e
Atributos ADMIN_* na matriz devCustomAttributes.
Por exemplo, o exemplo a seguir inclui três atributos personalizados:
BILLING_TYPE, SFID e ORG_EXT, no relatório (se definido)
para o desenvolvedor):
$ curl -H "Content-Type:application/json" -H "Accept: application/octet-stream" -X POST -d \ '{ "fromDate":"2015-07-01 00:00:00", "toDate":"2015-08-01 13:35:00", "showTxDetail":true, "showSummary":true, "transactionTypes":[ "PURCHASE", "CHARGE", "REFUND", "CREDIT", "SETUPFEES", "TERMINATIONFEES", "RECURRINGFEES" ], "currencyOption":"LOCAL", "groupBy":[ "PACKAGE", "PRODUCT", "DEVELOPER", "APPLICATION", "RATEPLAN" ], "devCustomAttributes": [ "BILLING_TYPE", "SFID", "ORG_EXT" ] }' \ "https://api.enterprise.apigee.com/v1/mint/organizations/{org_name}/revenue-reports" \ -u email:password
Veja a seguir um exemplo de saída de relatório que inclui valores para os dois tipos atributos:
Reporting Period:,From:,2015-07-01, To:,2015-07-31 API Product:,All Developer:,All Application:,All Currency:,Local Type of Report:,Summary Revenue Report Monetization Package,Package ID,API Product,Product ID,Developer Name,Developer ID,Application Name,Application ID,Rate Plan,Plan ID,Currency,Transaction Type,Provider Status,Total Volume,Charged Rate,BILLING_TYPE,SFID,ORG_EXT Location,location,foo_product,foo_product,Apigee,QQ7uxeMGf3w9W08B,my_app,my_app,rate_plan_1,location_rate_plan_1,USD,SETUPFEES,SUCCESS,1,15.0000,PREPAID,123,3AA, Location,location,foo_product,foo_product,BarCompany,barcompany,my_app,my_app,rate_plan_1,location_rate_plan_1,USD,SETUPFEES,SUCCESS,1,15.0000,PREPAID,123,3AA, Location,location,foo_product,foo_product,fremont,fremont,my_app,my_app,rate_plan_1,location_rate_plan_1,USD,SETUPFEES,SUCCESS,1,15.0000,PREPAID,123,3AA, Location,location,foo_product,foo_product,Juan's Taco Shack,juan-s-taco-sha,my_app,my_app,rate_plan_1,location_rate_plan_1,USD,SETUPFEES,SUCCESS,1,15.0000,PREPAID,123,3AA,
Como informar atividades de transações usando a API
Você pode visualizar a atividade de transação de uma organização emitindo uma solicitação POST para
/organizations/{org_name}/transaction-search: Ao fazer a solicitação, você precisa
especificar critérios para a recuperação. Você pode especificar alguns itens como critérios:
- ID de um ou mais produtos de API para os quais as transações foram emitidas.
- Mês e ano de faturamento das transações.
- Desenvolvedores que emitiram a transação.
- Tipo da transação, como compra e taxas de configuração.
- Status da transação como bem-sucedida e com falha.
Consulte Opções de configuração de critérios para ver a lista completa critérios.
O exemplo a seguir retorna transações emitidas por um desenvolvedor específico para o faturamento Junho de 2015:
$ curl -H "Content-Type:application/json" -X POST -d \
'{
"billingMonth": "JUNE",
"billingYear": 2015,
"devCriteria": [{
"id": "RtHAeZ6LtkSbEH56",
"orgId":"myorg"}],
"transactionTypes": ["PURCHASE", "CHARGE", "SETUPFEES"],
"transactionStatus": ["SUCCESS", "FAILED"]
}'
"https://api.enterprise.apigee.com/v1/mint/organizations/{org_name}/transaction-search \
-u email:password
Também é possível determinar quais aplicativos, desenvolvedores, pacotes de produtos de API ou produtos de API atividade de transação dentro de um determinado período. Você visualiza essas informações separadamente para cada tipo de objeto. Por exemplo, é possível visualizar informações específicas sobre aplicativos que acessam APIs nos seus pacotes de produtos de APIs monetizadas dentro de uma data de início e de término especificada.
Para visualizar informações sobre a atividade de transação, emita uma solicitação GET para um dos seguintes recursos:
| Recurso | Retorna |
|---|---|
/organizations/{org_name}/applications-with-transactions |
Aplicativos com transações |
/organizations/{org_name}/developers-with-transactions |
Desenvolvedores com transações |
/organizations/{org_name}/products-with-transactions |
Produtos com transações |
/organizations/{org_name}/packages-with-transactions |
Pacotes de produtos de API (ou pacotes de API) com transações |
Ao emitir a solicitação, você precisa especificar como parâmetros de consulta as datas de início e término para o período. Por exemplo, a solicitação a seguir retorna desenvolvedores com transações no mês de agosto de 2015.
$ curl -H "Accept:application/json" -X GET \
"https://api.enterprise.apigee.com/v1/mint/organizations/{org_name}/developers-with-transactions?START_DATE=2015-08-01&END_DATE=2015-08-31" \
-u email:password
A resposta deve ser semelhante a esta (apenas parte da resposta é exibida):
{ "developer" : [ { "address" : [ { "address1" : "Dev Five Address", "city" : "Pleasanton", "country" : "US", "id" : "0917f15f-9521-4e69-9376-07aa7b7b32ca", "isPrimary" : true, "state" : "CA", "zip" : "94588" } ], "approxTaxRate" : 0.0900, "billingType" : "POSTPAID", "broker" : false, "developerRole" : [ ], "email" : "dev5@myorg.com", "hasSelfBilling" : false, "id" : "tJZG6broTpGGGeLV", "legalName" : "DEV FIVE", "name" : "Dev Five", "organization" : { ... }, "registrationId" : "dev5", "status" : "ACTIVE", "type" : "UNTRUSTED" }, { "address" : [ { "address1" : "Dev Seven Address", "city" : "Pleasanton", "country" : "US", "id" : "f86d8c9f-6ed1-4323-b050-6adf494096c9", "isPrimary" : true, "state" : "CA", "zip" : "94588" } ], "approxTaxRate" : 0.0900, "billingType" : "POSTPAID", "broker" : false, "developerRole" : [ ], "email" : "dev7@myorg.com", "hasSelfBilling" : false, "id" : "VI3l8m8IPAvJTvjS", "legalName" : "DEV SEVEN", "name" : "Dev Seven", "organization" : { ... }, "registrationId" : "dev7", "status" : "ACTIVE", "type" : "UNTRUSTED" }, ... ] }
Opções de configuração de relatórios para a API
As seguintes opções de configuração de relatório estão disponíveis para a API:
| Nome | Descrição | Padrão | Obrigatório? |
|---|---|---|---|
name |
O nome do relatório. |
N/A | Sim |
description |
Uma descrição do relatório. |
N/A | Não |
mintCriteria |
Os critérios para configurar um relatório. Consulte Critérios de configuração do Terraform para mais detalhes. |
N/A | Não |
type |
O tipo do relatório. O papel pode ser um dos seguintes:
|
N/A | Sim |
Opções de configuração de critérios
As opções de configuração a seguir estão disponíveis para relatórios por meio da
Propriedade mintCriteria:
| Nome | Descrição | Padrão | Obrigatório? |
|---|---|---|---|
appCriteria |
ID e organização de um aplicativo específico a ser incluído no relatório. Se esse não for especificada, todos os aplicativos serão incluídos no relatório. |
N/A | Não |
billingMonth |
Observação:essa propriedade não é válida para relatórios de receita. Mês de faturamento do relatório, como JULHO. |
N/A | Sim |
billingYear |
Observação:essa propriedade não é válida para relatórios de receita. Ano de faturamento do relatório, como 2015. |
N/A | Sim |
currCriteria |
ID e organização de uma moeda específica a ser incluída no relatório. Se esse não for especificada, todas as moedas suportadas serão incluídas no relatório. |
N/A | Não |
currencyOption |
Moeda do relatório. Valores válidos:
|
N/A | Não |
devCriteria |
ID do desenvolvedor (endereço de e-mail) e nome da organização de um desenvolvedor específico incluído no relatório. Se esta propriedade não for especificada, todos os desenvolvedores serão incluídos no relatório. Exemplo: "devCriteria":[{
"id":"RtHAeZ6LtkSbEH56",
"orgId":"my_org"}
]
|
N/A | Não |
devCustomAttributes |
Observação:essa propriedade se aplica somente a relatórios de receita. Atributos personalizados a serem incluídos no relatório, se definidos para um desenvolvedor. Por exemplo: "devCustomAttributes": [
"custom_attribute1",
"custom_attribute2",
...
]Observação:não especifique os |
N/A | Não |
fromDate |
Observação:essa propriedade se aplica somente a receita, variação e relatórios de atividade de transações. Data de início do relatório em UTC. |
N/A | Obrigatório para relatórios de receita. não é necessário para outros tipos de relatório. |
groupBy |
Ordem em que as colunas são agrupadas no relatório. Valores válidos:
|
N/A | Não |
monetizationPackageId |
ID de um ou mais pacotes de produtos de API a serem incluídos no relatório. Se a propriedade não estiver especificado, todos os pacotes de produtos da API são incluídos no relatório. Observação : esta propriedade não é válida ao visualizar a atividade de transações ( |
N/A | Não |
pkgCriteria |
ID e organização de um pacote de produtos de API específico a ser incluído no relatório. Se esse
não for especificada, todos os pacotes de produtos da API serão incluídos no relatório. Essa propriedade pode
ser especificado em vez da propriedade Observação : essa propriedade não é válida ao visualizar a atividade de transações ( |
N/A | Não |
prevFromDate |
Observação:essa propriedade se aplica somente a relatórios de variações. Data de início de um período anterior em UTC. Usado para criar um relatório para uma campanha para comparação com um relatório atual. |
N/A | Não |
prevToDate |
Observação:essa propriedade se aplica somente a relatórios de variações. Data de término de um período anterior em UTC. Usado para criar um relatório para um período anterior para comparação com um relatório atual. |
N/A | Não |
prodCriteria |
ID e a organização de um produto de API específico a serem incluídos no relatório. Se esse
não for especificada, todos os produtos de API serão incluídos no relatório. Essa propriedade pode
ser especificado em vez da propriedade Observação : essa propriedade não é válida ao visualizar a atividade de transações ( |
N/A | Não |
productIds |
ID de um ou mais produtos da API a serem incluídos no relatório. Se a propriedade não estiver especificado, todos os produtos de API serão incluídos no relatório. Os IDs do produto da API precisam ser especificados como |
N/A | Não |
pricingTypes |
Tipo de preços do plano de tarifas a ser incluído no relatório. Valores válidos:
Se esta propriedade não for especificada, os planos de tarifas de todos os tipos de preços serão incluídos no no relatório. |
N/A | Não |
ratePlanLevels |
Tipo de plano de preços a ser incluído no relatório. Valores válidos:
Se esta propriedade não for especificada, os planos de tarifas padrão e específico para desenvolvedores serão incluído no relatório. |
N/A | Não |
showRevSharePct |
Sinalização que especifica se o relatório mostra porcentagens de participação na receita. Valores válidos incluem:
|
N/A | Não |
showSummary |
Sinalização que especifica se o relatório é um resumo. Valores válidos:
|
N/A | Não |
showTxDetail |
Observação:essa propriedade se aplica somente a relatórios de receita. Sinalização que especifica se o relatório mostra detalhes no nível da transação. Valores válidos incluem:
|
N/A | Não |
showTxType |
Sinalização que especifica se o relatório mostra o tipo de cada transação. Válida incluem:
|
N/A | Não |
toDate |
Observação:essa propriedade se aplica somente a receita, variação e relatórios de atividade de transações. Data de término do relatório em UTC. O relatório inclui dados coletados até o final do dia antes da data especificada. Os dados do relatório coletados na data de término especificada serão excluídos no relatório. Se você quiser que um plano de tarifas expire em 31 de dezembro de 2016, por exemplo, defina o valor toDate como 2017-01-01. Nesse caso, o relatório incluirá dados de relatório até o final do no dia 31 de dezembro de 2016; os dados do relatório de 1o de janeiro de 2017 serão excluídos. |
N/A | Obrigatório para relatórios de receita. não é necessário para outros tipos de relatório. |
transactionStatus |
Status das transações a serem incluídas no relatório. Valores válidos:
|
N/A | Não |
transactionCustomAttributes |
Atributos de transação personalizados a serem incluídos nos relatórios resumidos de receita. É necessário ativar esse recurso na sua organização. Consulte Como incluir de transação nos relatórios de resumo da receita. |
N/A | Não |
transactionTypes |
São os tipos de transações a serem incluídas no relatório. Valores válidos:
Se esta propriedade não for especificada, todos os tipos de transação serão incluídos no no relatório. |
N/A | Não |