Настройка политики записи транзакций

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

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

Введение

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

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

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

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

Настройка политики записи транзакций

Перейдите на страницу «Комплекты товаров», как описано ниже.

Настройка атрибутов транзакции

В разделе «Атрибуты транзакции» укажите критерии, указывающие на успешную транзакцию монетизации.

1. В поле «Критерии успешности транзакции» укажите выражение, основанное на значении атрибута «Статус» (описано далее), для определения момента успешного завершения транзакции (в целях начисления платы). Транзакции, которые не были успешными (то есть не соответствуют критериям в выражении), регистрируются, но тарифные планы к ним не применяются. Например:

   txProviderStatus == 'OK'

2. Атрибут «Статус» содержит значение, используемое выражением, настроенным в поле « Критерии успешного выполнения транзакции» . Настройте атрибут «Статус» , определив следующие поля:

   Поле	Описание
   Ресурс API	Шаблоны URI, определенные в API-продукте, будут использоваться для идентификации монетизированных транзакций.
   Место ответа	Место в ответе, где указан атрибут. Допустимые значения: переменная потока, заголовок, тело JSON и тело XML.
   Ценить	Значение ответа. Чтобы указать несколько значений, нажмите + Добавить x (например, + Добавить переменную потока ).

3. Для настройки необязательных атрибутов транзакции включите переключатель « Использовать необязательные атрибуты» и настройте любые атрибуты транзакции, определенные в следующей таблице.

   Атрибут	Описание
   Валовая цена	Этот атрибут применим только к тарифным планам, использующим модель распределения выручки. Для таких тарифных планов обязательным является либо значение «Валовая цена», либо значение «Чистая цена». Убедитесь, что числовое значение выражено в виде строки. Валовая цена транзакции. Для тарифных планов с распределением выручки необходимо указать либо атрибут «Валовая цена», либо атрибут «Чистая цена». Какой атрибут является обязательным, зависит от основы распределения выручки. Например, вы можете настроить тарифный план с распределением выручки, основанный на валовой цене транзакции. В этом случае поле «Валовая цена» является обязательным.
   Чистая цена	Этот атрибут применим только к тарифным планам, использующим модель распределения выручки. Для таких тарифных планов обязательным является либо поле «Валовая цена», либо поле «Чистая цена». Убедитесь, что числовое значение выражено в виде строки. Чистая цена транзакции. Для тарифных планов с распределением выручки необходимо указать либо поле «Чистая цена», либо поле «Валовая цена». Какое поле является обязательным, зависит от основы распределения выручки. Например, вы можете настроить тарифный план с распределением выручки, основанный на чистой цене транзакции. В этом случае поле «Чистая цена» является обязательным.
   Валюта	Этот атрибут обязателен для тарифных планов, использующих модель распределения доходов. Тип валюты, применяемый к транзакции.
   Код ошибки	Код ошибки, связанный с транзакцией. Он предоставляет дополнительную информацию о неудачной транзакции.
   Описание товара	Описание сделки.
   Налог	Этот атрибут актуален только для моделей распределения доходов и только в том случае, если сумма налога фиксируется в вызовах API. Убедитесь, что числовое значение выражено в виде строки. Сумма налога на покупку. Чистая цена плюс налог = валовая цена.

Например, задав следующие значения, система монетизации получает значение переменной потока из ответа на сообщение в переменной с именем response.reason.phrase . Если значение корректно и к запросу ProxyEndpoint API-прокси применяется политика проверки лимитов монетизации , система монетизации засчитывает его как транзакцию.

Настройка пользовательских атрибутов

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

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

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

Для настройки пользовательских атрибутов включите переключатель « Использовать пользовательские атрибуты» и определите до 10 пользовательских атрибутов. Для каждого пользовательского атрибута, который вы включаете в политику записи транзакций, необходимо указать следующую информацию.

Связывайте ресурсы с помощью уникального идентификатора транзакции.

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

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

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

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

Например, предположим, что вызов API резервирования и вызов API списания средств связаны следующим образом: поле с именем session_id в заголовке ответа от API резервирования соответствует заголовку ответа с именем reference_id от API списания средств. В этом случае вы можете установить значения в разделе «Связать ресурсы с уникальным идентификатором транзакции» следующим образом:

Настройка возврата средств

В разделе «Возвраты» вы указываете атрибуты, которые монетизация использует для обработки возвратов.

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

Для настройки возврата средств включите переключатель « Использовать атрибуты возврата» и укажите детали возврата:

1. Определите критерии возврата средств, задав следующие поля:

   Поле	Описание
   Место ответа	Ресурс для транзакции возврата средств. Если API-продукт предоставляет несколько ресурсов, вы можете выбрать только тот ресурс, который выполняет возврат средств.
   Критерии успешного возврата средств	Выражение, основанное на значении атрибута «Статус» (описано далее), используется для определения момента успешного завершения операции возврата средств (в целях начисления платы). Неуспешные операции возврата средств (то есть не соответствующие критериям выражения) регистрируются, но тарифные планы к ним не применяются. Например: txProviderStatus == 'OK'

2. Настройте атрибут «Статус» , определив следующие поля:

   Поле	Описание
   Место ответа	Место в ответе, где указан атрибут. Допустимые значения: переменная потока, заголовок, тело JSON и тело XML.
   Ценить	Значение ответа. Чтобы указать несколько значений, нажмите + Добавить x (например, + Добавить переменную потока ).

3. Настройте атрибут Parent ID , определив следующие поля:

   Поле	Описание
   Место ответа	Место в ответе, где указан атрибут. Допустимые значения: переменная потока, заголовок, тело JSON и тело XML.
   Ценить	Идентификатор транзакции, по которой обрабатывается возврат средств. Например, если пользователь покупает товар, а затем запрашивает возврат средств, идентификатором родительской транзакции будет идентификатор транзакции покупки. Чтобы указать несколько значений, нажмите + Добавить x (например, + Добавить переменную потока ).

4. Для настройки дополнительных атрибутов возврата средств включите переключатель «Использовать дополнительные атрибуты возврата средств» и настройте атрибуты. Дополнительные атрибуты возврата средств аналогичны дополнительным атрибутам транзакции, как определено в разделе «Настройка атрибутов транзакции» .

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

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

Создание политики записи транзакций с использованием API

Политика записи транзакций указывается в качестве атрибута API-продукта. Значение атрибута определяет:

• URI-суффикс ресурса продукта, к которому привязана политика записи транзакций. Суффикс включает переменную шаблона, заключенную в фигурные скобки. Переменная шаблона обрабатывается API-сервисами во время выполнения. Например, следующий URI-суффикс включает переменную шаблона {id} .

  /reserve/{id}**

  В этом случае API Services интерпретирует суффикс URI ресурса как /reserve , за которым следует любой подкаталог, начинающийся с идентификатора, определенного поставщиком API.

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

Атрибут политики записи транзакций добавляется к продукту API путем отправки PUT-запроса к API управления https://api.enterprise.apigee.com/v1/organizations/ {org_name} /apiproducts/ {apiproduct_Id} (а не к API монетизации).

Указание критериев успешного завершения транзакции с помощью API

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

Критерии успешности транзакции указываются в качестве атрибута продукта API. Для этого отправьте PUT-запрос к API управления https://api.enterprise.apigee.com/v1/organizations/ {org_name} /apiproducts/ {apiproduct_Id} (а не к API монетизации).

Например, в следующем запросе транзакция считается успешной, если значение параметра txProviderStatus равно success (критерии успешности транзакции выделены).

$ curl -H "Content-Type: application/json" -X PUT -d \ 
'{
        "apiResources": [
        "/reserve/{id}**"       
        ],
        "approvalType": "auto",
        "attributes": [                         
        {
                "name": "MINT_TRANSACTION_SUCCESS_CRITERIA",
                "value": "txProviderStatus == 'OK'"
        }
        ],
        "description": "Payment",
        "displayName": "Payment",
        "environments": [
        "dev"
        ],
        "name": "payment",
        "proxies": [],
        "scopes": [
        ""
        ]
}' \
"https://api.enterprise.apigee.com/v1/organizations/{org_name}/apiproducts/payment" \
-u email:password

Указание пользовательских атрибутов с помощью API

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

Пользовательские атрибуты указываются как атрибуты продукта API. Для этого отправьте PUT-запрос к API управления https://api.enterprise.apigee.com/v1/organizations/ {org_name} /apiproducts/ {apiproduct_Id} (а не к API монетизации).

Для каждого пользовательского атрибута, добавляемого к продукту API, необходимо указать имя и значение атрибута. Имя должно иметь формат MINT_CUSTOM_ATTRIBUTE_ {num} , где {num} — целое число.

Например, следующий запрос указывает три пользовательских атрибута.

$ curl -H "Content-Type: application/json" -X PUT -d \
'{
        "apiResources": [
        "/reserve/{id}**",
        "/charge/{id}**"
        ],
        "approvalType": "auto",
        "attributes": [
        {
                "name": "MINT_CUSTOM_ATTRIBUTE_1",
                "value": "test1"
        },
        {
                "name": "MINT_CUSTOM_ATTRIBUTE_2",
                "value": "test2"
        }
 
        ],
        "name": "payment",
        "proxies": [],
        "scopes": [
                ""
        ]
}' \
"https://api.enterprise.apigee.com/v1/organizations/{org_name}/apiproducts/payment" \
-u email:password

Примеры установки критериев успешности транзакций в политике регистрации транзакций.

В таблице ниже приведены примеры успешных и неуспешных транзакций, основанные на выражении критериев успешности транзакции и значении txProviderStatus , возвращаемом API-прокси. txProviderStatus — это внутренняя переменная, которую монетизация использует для определения успешности транзакции.