Как настроить правила записи транзакций

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

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

Введение

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

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

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

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

Как настроить правила записи транзакций

Перейдите на страницу "Наборы товаров", как описано ниже.

Как настроить атрибуты транзакций

В разделе Атрибуты транзакций укажите критерии, по которым определяется успешная транзакция монетизации.

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

   txProviderStatus == 'OK'

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

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

3. Чтобы настроить необязательные атрибуты транзакций, включите переключатель Использовать необязательные атрибуты и задайте любые атрибуты транзакций, перечисленные в таблице ниже.

   Атрибут	Описание
   Цена брутто	Этот атрибут можно использовать только для тарифных планов с моделью распределения дохода. Для этих тарифных планов обязательно указывать либо брутто-цену, либо нетто-цену. Убедитесь, что числовое значение выражено в виде строки. Полная цена транзакции. Если вы используете план с долей дохода, вам нужно указать атрибут "цена брутто" [gross_price] или "цена нетто" [net_price]. Какой атрибут обязателен, зависит от того, как распределяется доход. Например, вы можете настроить тарифный план с долей дохода, которая рассчитывается на основе валовой цены транзакции. В этом случае поле "Цена брутто" обязательно для заполнения.
   Стоимость обучения	Этот атрибут можно использовать только для тарифных планов с моделью распределения дохода. Для таких тарифных планов обязательно указывать либо брутто-цену, либо нетто-цену. Убедитесь, что числовое значение выражено в виде строки. Чистая цена транзакции. Для планов с долей дохода необходимо указать либо поле "Чистая цена", либо поле "Цена брутто". Требуемое поле зависит от того, на чем основано распределение дохода. Например, вы можете настроить тарифный план с долей дохода, основанный на чистой цене транзакции. В этом случае поле "Чистая цена" является обязательным.
   Валюта	Этот атрибут обязателен для тарифных планов с моделью распределения дохода. Тип валюты, используемой в транзакции.
   Код ошибки	Код ошибки, связанной с транзакцией. Он содержит дополнительную информацию о неудачной транзакции.
   Описание товара	Описание транзакции.
   Налог	Этот атрибут относится только к моделям с распределением дохода и только в том случае, если сумма налога передается в вызовах API. Убедитесь, что числовое значение выражено в виде строки. Сумма налога на покупку. Цена нетто + налог = цена брутто.

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

Как настроить настраиваемые атрибуты

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

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

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

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

Как связать ресурсы с уникальным идентификатором транзакции

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

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

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

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

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

Как настроить возврат средств

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

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

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

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

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

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

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

3. Настройте атрибут Идентификатор родительского элемента, заполнив следующие поля:

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

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

Как управлять правилами записи транзакций с помощью API

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

Как создать правило записи транзакций с помощью API

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

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

  /reserve/{id}**

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

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

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

Как задать критерии успешности транзакции с помощью API

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

Критерии успешности транзакции задаются как атрибут продукта API. Для этого отправьте запрос PUT к Management API https://api.enterprise.apigee.com/v1/organizations/{org_name}/apiproducts/{apiproduct_Id} (а не к Monetization 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 – это внутренняя переменная, которая используется для определения успешности транзакции.