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

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

Введение

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

Типы отчетов о монетизации

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

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

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

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

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

Дублирующиеся транзакции

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

Страница "Отчеты о монетизации"

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

Edge

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

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

Откроется страница "Отчеты".

Как показано на рисунке, на странице "Отчеты" можно:

Классическая версия Edge (частное облако)

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

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

Откроется страница "Отчеты".

Как настроить отчет

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

Как настроить отчет

Настройте отчет с помощью интерфейса Edge или классического интерфейса 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.

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

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

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

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

Как настроить отчет о балансе предоплаты

Настройте отчет и укажите на странице отчета следующую информацию:

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

Месяц, за который составлен отчет об оплате.
Уровень отчетности

Уровень отчетности. Действительные значения:

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

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

Как настроить отчет "Доход"

Настройте отчет и укажите на странице отчета следующую информацию:

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

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

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

Валюта для отчета. Действительные значения:

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

Уровень отчетности. Действительные значения:

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

Примечание. В классическом интерфейсе Edge пакеты продуктов API называются пакетами 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, а не по каждому из них отдельно.
Компании

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

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

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

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

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

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

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

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

Валюта для отчета. Действительные значения:

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

Порядок, в котором столбцы группируются и отображаются в отчете. Выберите номер, который указывает на относительный порядок этого раздела в группе (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 указывает, что столбцы в отчете будут сгруппированы в следующем порядке: PACKAGE, PRODUCT, DEVELOPER, APPLICATION и RATEPLAN (включает название тарифного плана и его идентификатор в отчете).

$ 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} – идентификатор конфигурации отчета (идентификатор возвращается в ответе при создании конфигурации отчета). Пример:

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

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

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

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

Примечание. Это свойство недействительно для отчетов о доходах.

Месяц оплаты для отчета, например "ИЮЛЬ".

 Н/Д Да
billingYear

Примечание. Это свойство недействительно для отчетов о доходах.

Год, за который создан отчет, например 2015.

 Н/Д Да
currCriteria

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

 Н/Д Нет
currencyOption

Валюта для отчета. Действительные значения:

  • LOCAL. Каждая строка отчета отображается с учетом применимого тарифного плана. Это означает, что в одном отчете может быть несколько валют, если у разработчиков есть планы с разными валютами.
  • EUR. Транзакции в местной валюте конвертируются и отображаются в евро.
  • GPB. Транзакции в местной валюте конвертируются и показываются в фунтах стерлингов.
  • USD. Транзакции в местной валюте конвертируются и показываются в долларах США.
 Н/Д Нет
devCriteria

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

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

Примечание. Это свойство применяется только к отчетам о доходах.

Специальные атрибуты, которые нужно включить в отчет (если они заданы для разработчика). Один из способов:

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

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

 Н/Д Нет
fromDate

Примечание. Это свойство применяется только к отчетам о доходе, отклонениях и действиях с транзакциями.

Дата начала отчета по UTC.

 Н/Д Обязательно для отчетов о доходе, но не для других типов отчетов.
groupBy

Порядок, в котором столбцы группируются в отчете. Действительные значения:

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

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

Примечание. Это свойство недействительно при просмотре действий с транзакциями (/transaction-search).

 Н/Д Нет
pkgCriteria

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

Примечание. Это свойство недействительно при просмотре действий с транзакциями (/transaction-search).

 Н/Д Нет
prevFromDate

Примечание. Это свойство применяется только к отчетам о расхождениях.

Дата начала предыдущего периода по UTC. Используется для создания отчета за предыдущий период, чтобы сравнить его с текущим.

 Н/Д Нет
prevToDate

Примечание. Это свойство применяется только к отчетам о расхождениях.

Дата окончания предыдущего периода в формате UTC. Используется для создания отчета за предыдущий период, чтобы сравнить его с текущим.

 Н/Д Нет
prodCriteria

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

Примечание. Это свойство недействительно при просмотре действий с транзакциями (/transaction-search).

 Н/Д Нет
productIds

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

Идентификаторы товаров в API должны быть указаны в формате org-name@@@product-name. Пример: "productIds": ["myorg@@@myproduct", "myorg@@@myproduct2"]

 Н/Д Нет
pricingTypes

Тип ценообразования тарифного плана, который нужно включить в отчет. Действительные значения:

  • REVSHARE. План распределения дохода.
  • REVSHARE_RATECARD. Доля дохода и тарифный план с тарифной сеткой.
  • RATECARD. Тарифный план.

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

 Н/Д Нет
ratePlanLevels

Тип тарифного плана, который нужно включить в отчет. Действительные значения:

  • DEVELOPERТарифный план для разработчиков.
  • STANDARD – стандартный тарифный план.

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

 Н/Д Нет
showRevSharePct

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

  • true. Показывайте доли дохода в процентах.
  • false. Не показывайте процентную долю дохода.
 Н/Д Нет
showSummary

Флаг, указывающий, является ли отчет сводным. Действительные значения:

  • trueОтчет представляет собой сводку.
  • falseОтчет не является сводным.
 Н/Д Нет
showTxDetail

Примечание. Это свойство применяется только к отчетам о доходах.

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

  • true – показать сведения на уровне транзакции.
  • false. Не показывайте сведения на уровне транзакций.
 Н/Д Нет
showTxType

Флаг, указывающий, будет ли в отчете показываться тип каждой транзакции. Допустимые значения:

  • true. Укажите тип каждой транзакции.
  • false. Не показывайте тип каждой транзакции.
 Н/Д Нет
toDate

Примечание. Это свойство применяется только к отчетам о доходе, отклонениях и действиях с транзакциями.

Конечная дата отчета по UTC.

Отчет содержит данные, собранные до конца дня, предшествующего указанной дате. Данные отчета, собранные в указанную дату окончания, будут исключены из отчета. Если вы хотите, чтобы тарифный план перестал действовать 31 декабря 2016 г., установите для параметра toDate значение 2017-01-01. В этом случае в отчет будут включены данные до конца дня 31 декабря 2016 г., а данные за 1 января 2017 г. будут исключены.

 Н/Д Обязательно для отчетов о доходе, но не для других типов отчетов.
transactionStatus

Статус транзакций, которые нужно включить в отчет. Действительные значения:

  • SUCCESS – успешная транзакция.
  • DUPLICATE. Повторяющаяся транзакция. Эти транзакции можно игнорировать. Канал передачи данных из среды выполнения Apigee на сервер рейтинга иногда может создавать дублирующиеся транзакции, чтобы обеспечить отказоустойчивость. Монетизация распознает и отмечает их как дубликаты.
  • FAILED. Не удалось выполнить транзакцию. Этот статус появляется, когда не удается выполнить проверку предварительного условия. Пример:
    • Попытка оценить приложение, хотя разработчик не приобрел тарифный план. Это может произойти, если не настроено правило "Проверка ограничений монетизации".
    • Квота превышена, но звонки продолжаются. Это может произойти, если не настроено правило "Проверка ограничений монетизации".
    • Для плана на основе специального атрибута было отправлено отрицательное значение специального атрибута.
  • INVALID_TSC. Транзакция недействительна. Этот статус возникает, когда критерии выполнения txProviderStatus не соответствуют критериям успеха, заданным на уровне пакета продуктов API.
  • REVIEW – транзакции, требующие проверки. Этот статус присваивается тарифным планам с гибкой долей дохода, если значение находится в диапазоне, который не настроен.
 Н/Д Нет
transactionCustomAttributes

Настраиваемые атрибуты транзакций, которые будут включены в сводные отчеты о доходах. Включите эту функцию в организации. Подробнее о том, как добавить в сводные отчеты о доходах специальные атрибуты транзакций…

 Н/Д Нет
transactionTypes

Тип транзакций, которые нужно включить в отчет. Действительные значения:

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

 Н/Д Нет