Управление отчетами

Вы просматриваете документацию Apigee Edge .
Перейдите в документацию Apigee X.info

Введение

Отчеты по монетизации позволяют получить доступ к целевой информации об использовании и транзакционной активности. Например, вы можете определить, какие приложения, разработчики, пакеты продуктов API или продукты API имели транзакционную активность в заданном диапазоне дат. С помощью монетизации вы можете создавать сводные или подробные отчеты, отслеживающие использование API.

Виды отчетов о монетизации

Вы можете создавать следующие типы отчетов по монетизации.

Отчет Описание
Выставление счетов Просмотрите активность разработчиков за один расчетный месяц и убедитесь, что тарифные планы были применены правильно.
Предоплаченный баланс Просмотрите пополнения баланса, произведенные разработчиком предоплаченных услуг в расчетном месяце или в текущем открытом месяце, чтобы сверить их с платежами, полученными от вашего платежного процессора.
Доход Просматривайте активность и доход, полученные разработчиками за определенный период времени, чтобы анализировать производительность ваших пакетов API-продуктов и самих продуктов среди разработчиков (и их приложений).
Дисперсия

Сравните активность и доход, полученные разработчиками за два разных периода времени, чтобы проанализировать тенденции роста или снижения производительности ваших API-пакетов и продуктов среди разработчиков (и их приложений).

О хранении данных

В публичном облаке Apigee Edge сохранение данных монетизации является частью тарифного плана. См. условия сохранения данных монетизации по адресу https://cloud.google.com/apigee/specsheets . Обратитесь в отдел продаж Apigee, если вы хотите, чтобы данные монетизации сохранялись после окончания срока действия соглашения. Расширенное сохранение данных активируется в момент запроса и не может быть активировано задним числом для включения данных, относящихся к периоду, предшествующему первоначальному сроку сохранения.

О дублирующихся транзакциях

Если сравнить отчеты о транзакциях монетизации с данными Analytics, можно заметить небольшое количество дублирующихся транзакций. Это ожидаемое поведение, поскольку система монетизации может обрабатывать несколько миллионов транзакций в день, при этом множество транзакций обрабатывается параллельно в любой момент времени. В среднем, дубликаты могут составлять около 0,1% транзакций.

Изучение страницы отчетов по монетизации

Перейдите на страницу отчетов по монетизации, как описано ниже.

Край

Чтобы получить доступ к странице отчетов с помощью интерфейса Edge:

  1. Войдите на сайт apigee.com/edge .
  2. В левой навигационной панели выберите «Публикация» > «Монетизация» > «Отчеты» .

Отображается страница «Отчеты».

Как показано на рисунке, страница «Отчеты» позволяет вам:

Классический Edge (частное облако)

Чтобы получить доступ к странице отчетов с помощью классического интерфейса Edge:

  1. Войдите в систему по http:// ms-ip :9000 , где ms-ip — это IP-адрес или DNS-имя узла сервера управления.
  2. В верхней панели навигации выберите «Монетизация» > «Отчеты по монетизации» .

Отображается страница «Отчеты».

Настройка отчета

Настройте отчет с помощью пользовательского интерфейса, как описано в следующих разделах.

Шаги по настройке отчета

Настройте отчет, используя пользовательский интерфейс Edge или классический пользовательский интерфейс Edge.

Край

Чтобы настроить отчет с помощью пользовательского интерфейса Edge:

  1. В левой навигационной панели выберите «Публикация» > «Монетизация» > «Отчеты» .
  2. Нажмите + Сообщить
  3. Настройте параметры отчета, указанные в следующей таблице.
    Поле Описание
    Имя Уникальное название отчета.
    Описание Описание отчета.
    Тип отчета См. Типы отчетов о монетизации .
  4. Настройте остальные параметры отчета в соответствии с выбранным типом отчета, как описано в следующих разделах:
  5. После ввода информации в окне отчета вы можете:
    • Нажмите «Сохранить отчет» , чтобы сохранить конфигурацию отчета.

    • Для получения подробного отчета нажмите кнопку «Отправить задание» , чтобы запустить отчет асинхронно и получить результаты позже. Дополнительные сведения см. в разделе «Создание и загрузка отчета» .

    • Нажмите «Сохранить как CSV» или «Сохранить как ZIP» , чтобы загрузить сгенерированный отчет на свой локальный компьютер в виде файла CSV (значения, разделенные запятыми) или сжатого ZIP-архива, содержащего CSV-файл. Для больших отчетов рекомендуется загрузка в формате ZIP, так как это обеспечит более эффективную загрузку.

Классический Edge (частное облако)

Чтобы создать отчет с помощью классического пользовательского интерфейса Edge:

  1. В верхней панели навигации выберите «Монетизация» > «Отчеты по монетизации» .
  2. В раскрывающемся меню выберите тип отчета, который вы хотите создать. См. Типы отчетов по монетизации .
  3. Нажмите + Сообщить .
  4. Настройте параметры отчета в зависимости от выбранного типа выставления счетов, как описано в следующих разделах:
  5. После ввода информации в окне отчета вы можете:
    • Нажмите «Сохранить как...» , чтобы сохранить конфигурацию отчета и загрузить его позже.

    • Чтобы получить подробный отчет, нажмите кнопку «Отправить задание» , чтобы запустить отчет синхронно и получить результаты позже. Дополнительные сведения см. в разделе «Создание и загрузка отчета» .

    • Нажмите «Скачать CSV» , чтобы сгенерировать и загрузить отчет на свой локальный компьютер в виде файла с разделителями-запятыми (CSV) для просмотра.

Настройка отчета по выставлению счетов

Выполните следующие действия для настройки отчета и введите следующую информацию на странице отчета:

Поле Описание
Месяц выставления счетов

Месяц выставления счетов за отчет.

Уровень отчетности

Уровень отчетности. Допустимые значения:

  • Подробный режим : отображает каждую транзакцию на отдельной строке и позволяет проверить правильность применения тарифных планов. Сводная информация отсутствует.
  • Краткое описание : Подводит итоги общей выручки по каждому API-продукту и разработчику.
Комплекты товаров

Примечание : В классическом пользовательском интерфейсе Edge пакеты продуктов API называются пакетами API.

Выберите пакеты продуктов API, которые следует включить в отчет. Если ни один пакет не выбран, в отчет будут включены все пакеты продуктов API.

В отчете для каждого выбранного пакета продуктов API предусмотрена отдельная строка.

Для сводного отчета можно дополнительно установить флажок «Не отображать» в параметрах отображения сводки. В этом случае отчет будет агрегировать информацию по всем (или выбранным) пакетам продуктов API (и не будет отображать информацию по каждому пакету продуктов API отдельно).

Продукты

Выберите продукты API, которые следует включить в отчет. Если ни один продукт не выбран, в отчет будут включены все продукты API.

В отчете для каждого выбранного активного фармацевтического ингредиента (АФИ) предусмотрена отдельная строка.

Для сводного отчета можно дополнительно установить флажок «Не отображать» в параметрах отображения сводки. В этом случае отчет будет агрегировать информацию по всем (или выбранным) разработчикам (и не будет отображать информацию по каждому выбранному разработчику отдельно).

Компании

Выберите компании, которые будут включены в отчет. Если ни одна компания не выбрана, в отчет будут включены все компании.

Тарифный план

Оцените планы, которые следует включить в отчет. Выберите один из следующих вариантов:

  • Все тарифные планы : Включите в отчет все тарифные планы.
  • Стандартные тарифные планы : В отчет следует включать только стандартные тарифные планы.
  • Тарифные планы, разработанные специально для застройщиков : В отчет следует включать только тарифные планы для застройщиков.

Настройка отчета о балансе предоплаченных счетов

Выполните следующие действия для настройки отчета и введите следующую информацию на странице отчета:

Поле Описание
Месяц выставления счетов

Месяц выставления счетов за отчет.

Уровень отчетности

Уровень отчетности. Допустимые значения:

  • Подробный режим : отображает каждое пополнение баланса отдельно и позволяет сверять платежи с платежами, полученными от вашей платежной системы.
  • Сводка : Подводит итоги пополнения баланса для каждого разработчика.
Компании

Выберите компании, которые будут включены в отчет. Если ни одна компания не выбрана, в отчет будут включены все компании.

Настройка отчета о доходах

Выполните следующие действия для настройки отчета и введите следующую информацию на странице отчета:

Поле Описание
Диапазон дат

Укажите диапазон дат для отчета. Выберите один из следующих вариантов:

  • Предварительные настройки : выберите один из стандартных диапазонов дат (например, «Последний календарный месяц») из выпадающего меню.
  • Пользовательские настройки : выберите начальную и конечную даты диапазона во всплывающем календаре.
Выберите валюту

Валюта для отчета. Допустимые значения:

  • Местная валюта : Каждая строка отчета отображается в соответствии с применимым тарифным планом. Это означает, что в одном отчете может быть несколько валют, если у разработчиков есть тарифные планы, использующие разные валюты.
  • Евро : Операции в местной валюте в отчете конвертируются и отображаются в евро.
  • Фунт стерлингов : Операции в местной валюте в отчете конвертируются и отображаются в фунтах стерлингов.
  • Доллары США : Операции в местной валюте в отчете конвертируются и отображаются в долларах.
Уровень отчетности

Уровень отчетности. Допустимые значения:

  • Подробный режим : каждая транзакция отображается на отдельной строке. Сводка отсутствует.
  • Сводка : Подводит итоги общей выручки по каждому API-продукту и разработчику в зависимости от выбранных вами параметров.
Комплекты товаров

Примечание : В классическом пользовательском интерфейсе Edge пакеты продуктов API называются пакетами API.

Выберите пакеты продуктов API, которые следует включить в отчет. Если ни один пакет не выбран, в отчет будут включены все пакеты продуктов API.

В отчете для каждого выбранного пакета продуктов API предусмотрена отдельная строка.

Для сводного отчета можно дополнительно установить флажок «Не отображать» в параметрах отображения сводки. В этом случае отчет будет агрегировать информацию по всем (или выбранным) пакетам продуктов API (и не будет отображать информацию по каждому пакету продуктов API отдельно).

Продукты

Выберите продукты API, которые следует включить в отчет. Если ни один продукт не выбран, в отчет будут включены все продукты API.

В отчете для каждого выбранного активного фармацевтического ингредиента (АФИ) предусмотрена отдельная строка.

Для сводного отчета можно дополнительно установить флажок «Не отображать» в параметрах отображения сводки. В этом случае отчет будет агрегировать информацию по всем (или выбранным) разработчикам (и не будет отображать информацию по каждому выбранному разработчику отдельно).

Компании

Выберите компании, которые будут включены в отчет. Если ни одна компания не выбрана, в отчет будут включены все компании.

Для сводного отчета можно дополнительно установить флажок «Не отображать» в разделе «Параметры отображения сводного отчета». В этом случае отчет будет агрегировать информацию по всем (или выбранным) компаниям (и не будет отображать информацию по каждой выбранной компании отдельно).

Приложения

Выберите приложения, которые следует включить в отчет. Если ни одно приложение не выбрано, в отчет будут включены все приложения.

В отчете для каждого выбранного приложения предусмотрена отдельная строка.

Для сводного отчета можно дополнительно установить флажок «Не отображать» в разделе «Параметры отображения сводного отчета». В этом случае отчет будет агрегировать информацию по всем (или выбранным) приложениям (и не будет отображать информацию по каждому выбранному приложению отдельно).

Параметры отображения сводки

Порядок группировки и отображения столбцов в отчете. Выберите число, указывающее относительный порядок этого раздела в группировке (1 — первая группировка). Например, следующая группировка сначала по пакетам, затем по продуктам, затем по разработчикам, затем по приложениям.

Если вы не хотите отображать раздел, выберите «Не отображать» , а затем выберите остальные поля по порядку. Порядок автоматически обновляется при изменении относительного порядка раздела или при решении не отображать раздел в отчете.

Включение пользовательских атрибутов транзакций в сводные отчеты о доходах.

Политики записи транзакций позволяют собирать пользовательские атрибутивные данные из транзакций, и вы можете включать эти пользовательские атрибуты в сводные отчеты о доходах. Определите набор пользовательских атрибутов по умолчанию, включенных в таблицы базы данных монетизации, установив свойство MINT.SUMMARY_CUSTOM_ATTRIBUTES для вашей организации.

Использование этой функции требует некоторого обдумывания и планирования, поэтому ознакомьтесь с приведенными ниже рекомендациями.

Если вы являетесь клиентом облачной платформы, обратитесь в службу поддержки Apigee Edge , чтобы установить это свойство. Если вы являетесь клиентом Apigee Edge для частного облака, установите флаг с помощью PUT-запроса к следующему API, используя учетные данные системного администратора.

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">[&quot;partner_id&quot;,&quot;tax_source&quot;]</Property>
        <Property name="features.topLevelDevelopersAreCompanies">false</Property>
    </Properties>
</Organization>"

В этом примере вызов API активирует функцию и добавляет столбцы partner_id и tax_source в базу данных монетизации. Обратите внимание, что массив пользовательских атрибутов в вызове API закодирован в формате URL.

Рекомендации по включению пользовательских атрибутов транзакций в отчеты.

  • Перед созданием атрибутов с помощью API убедитесь в правильности их названий. Это названия столбцов в базе данных, и данные пользовательских атрибутов всегда хранятся там.
  • В каждой политике регистрации транзакций доступно 10 слотов для пользовательских атрибутов, как показано на следующем изображении. Используйте одинаковые имена и позиции атрибутов для всех продуктов, которые будут включены в отчеты. Например, в следующей политике регистрации транзакций пользовательские атрибуты partner_id и tax_source занимают поля 4 и 5 соответственно. Это должно быть их имя и позиция во всех политиках регистрации транзакций для продуктов, которые будут включены в отчеты.

Чтобы включить пользовательские атрибуты в сводный отчет о доходах после активации этой функции, используйте API отчетов, добавив transactionCustomAttributes в MintCriteria . См. Параметры конфигурации критериев .

Настройка отчета об отклонениях (устаревшая функция)

Выполните следующие действия для настройки отчета и введите следующую информацию на странице отчета:

Поле Описание
Диапазон дат

Укажите диапазон дат для отчета. Выберите один из следующих вариантов:

  • Предварительные настройки : выберите один из стандартных диапазонов дат (например, «Последний календарный месяц») из выпадающего меню.
  • Пользовательские настройки : выберите начальную и конечную даты диапазона во всплывающем календаре.
Пакеты

Пакеты API, которые необходимо включить в отчет. Выберите один из следующих вариантов:

  • Все : включает все пакеты API, указанные в отчете.
  • Выбрано : Отображает список, из которого можно выбрать пакеты API для включения в отчет. Если не выбрать ни одного пакета, в отчет будут включены все пакеты.

В отчете для каждого выбранного пакета API предусмотрена отдельная строка.

Для создания сводного отчета можно дополнительно установить флажок «Не отображать (пакеты)» в разделе «Параметры отображения сводной информации». В этом случае отчет будет агрегировать информацию по всем (или выбранным) пакетам API (и не будет отображать информацию по каждому пакету API отдельно).

Продукты

API-продукты, которые следует включить в отчет. Выберите один из следующих вариантов:

  • Все : включает все продукты API, представленные в отчете.
  • Выбрано : Отображает список, из которого можно выбрать товары для включения в отчет. Если не выбрать ни одного товара, в отчет будут включены все товары.

В отчете для каждого выбранного активного фармацевтического ингредиента (АФИ) предусмотрена отдельная строка.

Для создания сводного отчета можно дополнительно установить флажок «Не отображать (продукты)» в разделе «Параметры отображения сводного отчета». В этом случае отчет будет агрегировать информацию по всем (или выбранным) продуктам API (и не будет отображать информацию по каждому продукту API отдельно).

Компании

Компании, которые следует включить в отчет. Выберите одну из следующих:

  • Все : включает все компании, упомянутые в отчете.
  • Выбранные : Отображает список, из которого можно выбрать компании для включения в отчет. Если не выбрать ни одной компании, в отчет будут включены все компании.

В отчете для каждой выбранной компании предусмотрена отдельная строка.

Для создания сводного отчета можно дополнительно установить флажок «Не отображать (компании)» в разделе «Параметры отображения сводного отчета». В этом случае отчет будет агрегировать информацию по всем (или выбранным) компаниям (и не будет отображать информацию по каждой выбранной компании отдельно).

Приложения

Список приложений, которые следует включить в отчет. Выберите одно из следующих:

  • Все : включает все приложения, указанные в отчете.
  • Выбранные : Отображает список, из которого можно выбрать приложения для включения в отчет. Если не выбрать ни одного приложения, в отчет будут включены все приложения.

В отчете для каждого выбранного приложения предусмотрена отдельная строка.

Для создания сводного отчета можно дополнительно установить флажок «Не отображать (приложения)» в разделе «Параметры отображения сводного отчета». В этом случае отчет будет агрегировать информацию по всем (или выбранным) приложениям (и не будет отображать информацию по каждому выбранному приложению отдельно).

Валюта

Валюта для отчета. Допустимые значения:

  • Местная валюта : Каждая строка отчета отображается в соответствии с применимым тарифным планом. Это означает, что в одном отчете может быть несколько валют, если у разработчиков есть тарифные планы, использующие разные валюты.
  • EUR : Операции в местной валюте в отчете конвертируются и отображаются в евро.
  • GPB : Операции в местной валюте в отчете конвертируются и отображаются в фунтах стерлингов.
  • USD : Операции в местной валюте, указанные в отчете, конвертируются и отображаются в долларах США.
Параметры отображения сводки

Порядок группировки и отображения столбцов в отчете. Выберите число, указывающее относительный порядок этого раздела в группировке (1 — первая группировка). Например, следующая группировка сначала по пакетам, затем по продуктам, затем по разработчикам, затем по приложениям.

Если вы не хотите отображать раздел, выберите «Не отображать» , а затем выберите остальные поля по порядку. Порядок автоматически обновляется при изменении относительного порядка раздела или при решении не отображать раздел в отчете.

Создание и загрузка отчета

После создания отчета вы можете загрузить его результаты в формате CSV или ZIP. Создание CSV- или ZIP-файла может происходить синхронно или асинхронно .

  • При синхронном создании отчета вы отправляете запрос на его выполнение, и запрос блокируется до тех пор, пока аналитический сервер не предоставит ответ. Однако, поскольку отчету может потребоваться обработать большой объем данных (например, сотни гигабайт), синхронный отчет может завершиться с ошибкой из-за превышения времени ожидания.

    Уровень сводного отчета поддерживает только синхронную генерацию.

  • При асинхронном формировании отчета вы запускаете запрос на создание отчета и получаете результаты позже. Асинхронная обработка запросов может быть хорошей альтернативой в следующих ситуациях:

    • Анализ и составление отчетов, охватывающих длительные временные интервалы.
    • Анализ данных с использованием различных параметров группировки и других ограничений, усложняющих запрос.
    • Управление запросами в случае значительного увеличения объемов данных у некоторых пользователей или организаций.

    Уровень детализации отчета поддерживает асинхронную генерацию.

Для создания и загрузки отчета в формате CSV или ZIP выполните одно из следующих действий:

  1. Перейдите на страницу «Отчеты».
  2. Наведите курсор на отчет, который хотите загрузить.

  3. В столбце «Изменено» выберите один из следующих вариантов:

    1. Он значок CSV-файла иконка или значок zip-файла значок (для сводного отчета). Отчет синхронно сохраняется в CSV- или ZIP-файл.
    2. Отправьте задание (для получения подробного отчета). Асинхронное задание запускается.

      1. Отслеживайте статус задания в столбце «Изменено» .

        Значок диска появляется, когда отчет готов к загрузке:

        Образ диска появляется, когда отчет готов к загрузке.
      2. После завершения работы нажмите на значок диска , чтобы загрузить отчет.

Ниже приведён пример CSV-файла для сводного отчёта по выставлению счетов.

Редактирование отчета

Чтобы отредактировать отчет:

  1. Перейдите на страницу «Отчеты» .
  2. Наведите курсор на отчет, который хотите отредактировать, и щелкните. в меню действий.
  3. При необходимости обновите конфигурацию отчета.
  4. Нажмите «Обновить отчет» , чтобы сохранить обновленную конфигурацию отчета.

Удаление отчета

Чтобы удалить отчёт:

  1. Перейдите на страницу «Отчеты» .
  2. Наведите курсор на отчет, который хотите удалить.
  3. Нажмите в меню действий.

Управление отчетами по монетизации с помощью API.

В следующих разделах описано, как управлять отчетами о монетизации с помощью API.

Настройка отчета с использованием API

Чтобы настроить отчет для всей организации, отправьте POST-запрос по адресу /organizations/{org_name}/report-definitions .

Чтобы настроить отчет для конкретного разработчика, отправьте POST-запрос по адресу /organizations/{org_name}/developers/{dev_id}/report-definitions , где {dev_id} — это идентификатор разработчика.

При отправке запроса необходимо указать имя и тип отчета. Тип может быть одним из следующих: BILLING , REVENUE , VARIANCE (устаревшее) или PREPAID_BALANCE . Кроме того, в свойстве mintCriteria можно указать критерии, которые дополнительно настраивают отчет. Существует широкий спектр критериев, которые можно указать. Это дает большую гибкость при настройке отчета. Вот некоторые из критериев, которые можно указать:

  • Для отчета о балансе по счетам или предоплаченным счетам указывается месяц выставления счета для отчета.
  • В отчете о доходах указываются типы операций, отраженные в отчете, такие как операции покупки, операции списания средств и возвраты средств.
  • Для получения отчета о балансе предоплаченных услуг необходимо указать застройщика, к которому относится отчет.
  • Для составления отчета о доходах необходимо указать пакеты продуктов API (или API-пакеты), продукты, тарифные планы и приложения, к которым относится отчет.
  • Для отчета о доходах или отклонениях указывается соответствующая валюта отчета.
  • Для отчетов по выставлению счетов, предоплаченным балансам или доходам, независимо от того, является ли отчет сводным или подробным.
  • Для составления сводного отчета о доходах добавьте в него пользовательские атрибуты транзакций.

Полный список критериев отчета см. в разделе «Параметры конфигурации отчета» .

Например, следующий код создает отчет о доходах, который суммирует транзакционную активность за июль 2015 года. Отчет включает различные типы транзакций, указанные в свойстве transactionTypes , и применяется специально к пакету продуктов Payment API и продукту Payment API. Поскольку в определении отчета не указан конкретный разработчик или приложение, отчет применяется ко всем разработчикам и приложениям. А поскольку свойство currencyOption установлено в LOCAL , каждая строка отчета будет отображаться с использованием валюты соответствующего тарифного плана. Кроме того, свойство groupBy указывает, что столбцы в отчете будут сгруппированы в следующем порядке: ПАКЕТ, ПРОДУКТ, РАЗРАБОТЧИК, ПРИЛОЖЕНИЕ и ТАРИФНЫЙ ПЛАН (включает название и идентификатор тарифного плана в отчете).

$ 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

Следующая команда создает подробный отчет о выставлении счетов, отображающий активность разработчика DEV FIVE за июнь 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

Просмотр настроек отчетов с помощью API

Вы можете просмотреть конфигурацию конкретного отчета или все конфигурации отчетов для организации. Вы также можете просмотреть конфигурации отчетов для отдельного разработчика.

Чтобы просмотреть конфигурацию конкретного отчета для организации, отправьте GET-запрос по адресу /organizations/{org_name}/report-definitions/{report_definition_id} , где {report_definition_id} — это идентификатор конкретной конфигурации отчета (ID возвращается в ответе при создании конфигурации отчета). Например:

$ 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

Чтобы просмотреть все настройки отчетов для организации, отправьте GET-запрос по адресу /organizations/{org_name}/report-definitions .

Для фильтрации и сортировки результатов можно передать следующие параметры запроса:

Параметр запроса Описание
all Флаг, определяющий, следует ли возвращать все пакеты продуктов API. Если установлено значение false , количество возвращаемых пакетов продуктов API на странице определяется параметром запроса size . По умолчанию — false .
size Количество пакетов продуктов API, возвращаемых на странице. По умолчанию — 20. Если параметр запроса all установлен в true , этот параметр игнорируется.
page Номер страницы, которую вы хотите вернуть (если контент постраничный). Если параметр запроса all установлен в true , этот параметр игнорируется.
sort Поле, по которому следует сортировать информацию. Если параметр запроса all установлен в true , этот параметр игнорируется. По умолчанию используется значение UPDATED:DESC .

Например, следующий запрос возвращает конфигурации отчетов для организации и ограничивает количество получаемых конфигураций отчетов максимум пятью:

$ curl -H "Accept:application/json" -X GET \ 
"https://api.enterprise.apigee.com/v1/mint/organizations/{org_name}/report-definitions?size=5" \ 
-u email:password

Ответ должен выглядеть примерно так (показана только часть ответа):

{
  "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
}

Чтобы просмотреть настройки отчетов для конкретного разработчика, отправьте GET-запрос по адресу /organizations/{org_name}/developers/{dev_id}/report-definitions , где {dev_id} — это идентификатор разработчика. При отправке запроса вы можете указать описанные выше параметры запроса для фильтрации и сортировки данных.

Например, следующий запрос возвращает конфигурации отчетов для конкретного разработчика и сортирует ответ по имени отчета:

$ 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

Обновление конфигурации отчета с помощью API

Для обновления конфигурации отчета отправьте PUT-запрос по адресу /organizations/{org_name}/report-definitions/{report_definition_id} , где {report_definition_id} — это идентификатор конкретной конфигурации отчета. При обновлении необходимо указать в теле запроса обновленные значения конфигурации и идентификатор конфигурации отчета. Например, следующий запрос обновляет отчет до сводного (обновленные свойства выделены):

$ 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

Ответ должен выглядеть примерно так (показана только часть ответа):

{
 "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"
}

Удаление конфигурации отчета с помощью API

Для удаления конфигурации отчета отправьте запрос DELETE по адресу /organizations/{org_namer}/report-definitions/{report_definition_id} , где {report_definition_id} — это идентификатор конфигурации отчета, которую необходимо удалить. Например: 

$ 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

Создание отчета с использованием API

После настройки отчета вы можете сгенерировать его в формате CSV (значения, разделенные запятыми) для просмотра.

Для создания отчета отправьте POST-запрос на адрес organizations/{org_id}/{report_type} , где {report_type} указывает тип отчета, который вы хотите создать. Доступные типы:

  • billing-reports
  • revenue-reports
  • prepaid-balance-reports
  • variance-reports
Кроме того, вы можете сформировать отчет о доходах для конкретного разработчика, как описано в разделе «Форматирование отчета о доходах для разработчика» .

Например, для создания отчета по выставлению счетов отправьте POST-запрос по адресу organizations/{org_name}/billing-reports .

В теле запроса (для любого типа отчета) укажите критерии поиска для отчета. Используйте свойства mintCriteria для указания критериев поиска. Дополнительные сведения см. в разделе «Параметры конфигурации критериев» .

Например, следующий запрос ищет отчет о доходах на основе различных критериев, таких как даты начала и окончания отчета, а также типы транзакций.

$ 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

Если отчет о доходах найден, он генерируется в формате CSV. Ниже приведен пример выходного отчета: 

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,

Включение пользовательских атрибутов разработчиков в отчеты о доходах с помощью API.

В отчеты о доходах можно включать пользовательские атрибуты, если они определены для разработчика. Пользовательские атрибуты определяются при добавлении разработчиков в организацию, как описано в разделе «Управление разработчиками приложений» .

Чтобы добавить пользовательские атрибуты в отчет о доходах, отправьте POST-запрос на адрес organizations/{org_name}/revenue-reports и включите массив devCustomAttributes в тело запроса: 

"devCustomAttributes": [
    "custom_attribute1",
    "custom_attribute2",
    ...
]

Примечание: Не указывайте предопределенные атрибуты MINT_* и ADMIN_* в массиве devCustomAttributes .

Например, в следующем примере отчет включает три пользовательских атрибута: BILLING_TYPE , SFID и ORG_EXT (если они определены для разработчика): 

$ 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

Ниже приведён пример выходных данных отчёта, включающих значения двух пользовательских атрибутов: 

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,

Отслеживание транзакционной активности с помощью API

Вы можете просмотреть историю транзакций организации, отправив POST-запрос на /organizations/{org_name}/transaction-search . При отправке запроса необходимо указать критерии для получения данных. В качестве критериев можно указать, например, следующие:

  • Идентификатор одного или нескольких продуктов API, для которых были совершены транзакции.
  • Месяц и год выставления счетов по транзакциям.
  • Разработчик(и), инициировавший(ие) транзакцию.
  • Тип транзакции, например, покупка и плата за настройку.
  • Статус транзакции: успешная или неудачная.

Полный список критериев см. в разделе «Параметры настройки критериев».

Например, ниже приведены данные о возвратах транзакций, оформленных конкретным разработчиком за расчетный месяц июнь 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

Вы также можете определить, какие приложения, разработчики, пакеты продуктов API или продукты API имели транзакционную активность в заданном диапазоне дат. Эта информация просматривается отдельно для каждого типа объекта. Например, вы можете просмотреть информацию конкретно о приложениях, которые обращаются к API в ваших монетизированных пакетах продуктов API в течение указанных начальных и конечных дат.

Для просмотра информации о транзакциях отправьте GET-запрос к одному из следующих ресурсов:

Ресурс Возвраты
/organizations/{org_name}/applications-with-transactions

Приложения с транзакциями

/organizations/{org_name}/developers-with-transactions

Разработчики, использующие транзакции

/organizations/{org_name}/products-with-transactions

Товары с транзакциями

/organizations/{org_name}/packages-with-transactions

Пакеты продуктов API (или API-пакеты) с транзакциями

При отправке запроса необходимо указать в качестве параметров запроса начальную и конечную даты для диапазона дат. Например, следующий запрос вернет разработчиков с транзакциями за август 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

Ответ должен выглядеть примерно так (показана только часть ответа): 

{
  "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"
  }, ...
  ]
}

Параметры конфигурации отчета для API

Для API доступны следующие параметры конфигурации отчета:

Имя Описание По умолчанию Необходимый?
name

Название отчета.

 Н/Д Да
description

Описание отчета.

 Н/Д Нет
mintCriteria

Критерии для настройки отчета. Дополнительные сведения см. в разделе «Параметры настройки критериев» .

 Н/Д Нет
type

Тип отчета. Значение может быть одним из следующих:

  • BILLING
  • REVENUE
  • VARIANCE
  • PREPAID_BALANCE
 Н/Д Да

Параметры конфигурации критериев

Для отчетов через свойство mintCriteria доступны следующие параметры конфигурации:

Имя Описание По умолчанию Необходимый?
appCriteria

Идентификатор и название организации для конкретного приложения, которое будет включено в отчет. Если это свойство не указано, в отчет будут включены все приложения.

 Н/Д Нет
billingMonth

Note: This property is not valid for revenue reports.

Billing month for the report, such as JULY.

 Н/Д Да
billingYear

Note: This property is not valid for revenue reports.

Billing year for the report, such as 2015.

 Н/Д Да
currCriteria

ID and organization for a specific currency to be included in the report. If this property is not specified, all supported currencies are included in the report.

 Н/Д Нет
currencyOption

Currency for the report. Valid values include:

  • LOCAL . Each line of the report is displayed using the applicable rate plan. This means that there may be multiple currencies in one report if the developers have plans that use different currencies.
  • EUR . Local currency transactions are converted and displayed in Euros.
  • GPB . Local currency transactions are converted and displayed in United Kingdom pounds.
  • USD . Local currency transactions are converted and displayed in United States dollars.
 Н/Д Нет
devCriteria

Developer ID (email address), and organization name for a specific developer to be included in the report. If this property is not specified, all developers are included in the report. For example: 

"devCriteria":[{
    "id":"RtHAeZ6LtkSbEH56",
    "orgId":"my_org"}
]
Н/Д Нет
devCustomAttributes

Note: This property applies only to revenue reports.

Custom attributes to include in the report, if defined for a developer. For example: 

"devCustomAttributes": [
    "custom_attribute1",
    "custom_attribute2",
    ...
]

Note: Do not specify the predefined MINT_* and ADMIN_* attributes in the devCustomAttributes array.

 Н/Д Нет
fromDate

Note: This property applies only to revenue, variance, and transaction activity reports.

Starting date of the report in UTC.

 Н/Д Required for revenue reports; not required for other report types.
groupBy

Order in which columns are grouped in the report. Valid values include:

  • APPLICATION
  • BALANCE
  • DEVELOPER
  • ORG
  • PACKAGE
  • PRODUCT
  • RATEPLAN
 Н/Д Нет
monetizationPackageId

ID of one or more API product bundles to include in the report. If this property is not specified, all API product bundles are included in the report.

Note: This property is not valid when viewing the transaction activity ( /transaction-search ).

 Н/Д Нет
pkgCriteria

ID and organization for a specific API product bundle to be included in the report. If this property is not specified, all API product bundles are included in the report. This property can be specified instead of the monetizationpackageIds property.

Note: This property is not valid when viewing the transaction activity ( /transaction-search ).

 Н/Д Нет
prevFromDate

Note: This property applies only to variance reports.

Starting date of a previous period in UTC. Used to create a report for a previous period for comparison against a current report.

 Н/Д Нет
prevToDate

Note: This property applies only to variance reports.

Ending date of a previous period in UTC. Used to create a report for a previous period for comparison against a current report.

 Н/Д Нет
prodCriteria

ID and organization for a specific API product to be included in the report. If this property is not specified, all API products are included in the report. This property can be specified instead of the productIds property.

Note: This property is not valid when viewing the transaction activity ( /transaction-search ).

 Н/Д Нет
productIds

ID of one or more API products to include in the report. If this property is not specified, all API products are included in the report.

API product IDs should be specified as org-name@@@product-name . For example: "productIds": ["myorg@@@myproduct", "myorg@@@myproduct2"]

 Н/Д Нет
pricingTypes

Pricing type of rate plan to be included in the report. Valid values include:

  • REVSHARE . Revenue share plan.
  • REVSHARE_RATECARD . Revenue share and rate card rate plan.
  • RATECARD . Rate card plan.

If this property is not specified, rate plans of all pricing types are included in the report.

 Н/Д Нет
ratePlanLevels

Type of rate plan to be included in the report. Valid values include:

  • DEVELOPER . Developer rate plan.
  • STANDARD . Standard rate plan.

If this property is not specified, both developer-specific and standard rate plans are included in the report.

 Н/Д Нет
showRevSharePct

Flag that specifies whether the report shows revenue share percentages. Valid values include:

  • true . Show revenue share percentages.
  • false . Do not show revenue share percentages.
 Н/Д Нет
showSummary

Flag that specifies whether the report is a summary. Valid values include:

  • true . Report is a summary.
  • false . Report is not a summary.
 Н/Д Нет
showTxDetail

Note: This property applies only to revenue reports.

Flag that specifies whether the report shows transaction level details. Valid values include:

  • true . Show transaction-level details.
  • false . Do not show transaction-level details.
 Н/Д Нет
showTxType

Flag that specifies whether the report shows the type of each transaction. Valid values include:

  • true . Show the type of each transaction.
  • false . Do not show the type of each transaction.
 Н/Д Нет
toDate

Note: This property applies only to revenue, variance, and transaction activity reports.

End date of the report in UTC.

The report includes data collected up to the end of day before the date specified. Report data collected on the specified end date will be excluded from the report. If you want to expire a rate plan on December 31, 2016, for example, you should set the toDate value to 2017-01-01. In this case, the report will include report data up to the end of the day on December 31, 2016; report data on January 1, 2017 will be excluded.

 Н/Д Required for revenue reports; not required for other report types.
transactionStatus

Status of transactions to include in the report. Valid values include:

  • SUCCESS . Successful transaction.
  • DUPLICATE . Duplicate transaction. These transactions can be ignored. The data pipeline from the Apigee runtime to the rating server can sometimes generate duplicate transactions in order to be fault tolerant and monetization recognizes and marks them as duplicate.
  • FAILED . Failed transaction. This status is triggered when the validation of a precondition fails. For example:
    • Rating attempted even though the developer has not purchased rate plan. This can occur if the Monetization Limits Check policy is not configured.
    • Quota is exceeded, but calls still continue. This can occur if the Monetization Limits Check policy is not configured.
    • Negative custom attribute value was sent for custom attribute-based plan.
  • INVALID_TSC . Transaction is invalid. This status is triggered when the txProviderStatus runtime criteria does not match the success criteria specified at the API product bundle-level.
  • REVIEW . Transactions requiring review. This status is triggered for flexible revenue share rate plans if the value falls within a revenue range that is not configured.
 Н/Д Нет
transactionCustomAttributes

Custom transaction attributes to include in summary revenue reports. You must enable this feature in your organization. See Including custom transaction attributes in revenue summary reports .

 Н/Д Нет
transactionTypes

Type of transactions to be included in the report. Valid values include:

If this property is not specified, all transaction types are included in the report.

 Н/Д Нет