Konfigurowanie zasad rejestrowania transakcji

Wyświetlasz dokumentację Apigee Edge.
Otwórz dokumentację Apigee X. info

Skonfiguruj zasady rejestrowania transakcji dla każdego produktu interfejsu API w pakiecie produktów interfejsu API zgodnie z opisem w sekcjach poniżej.

Wprowadzenie

Zasady rejestrowania transakcji umożliwiają zarabianie na treściach poprzez rejestrowanie parametrów transakcji i atrybutów niestandardowych. Informacje te są potrzebne do przetwarzania danych związanych z generowaniem przychodu, np. do stosowania planów stawek.

Jeśli na przykład skonfigurujesz plan stawek za udział w przychodach, procent przychodów generowanych przez każdą transakcję związaną z Twoim produktem API, który generuje przychody, będzie dzielony z deweloperem aplikacji wysyłającej żądanie. Podział przychodów jest oparty na cenie netto lub brutto transakcji (określasz, która z nich ma być używana), czyli do określenia podziału przychodów używany jest procent ceny brutto lub netto każdej transakcji. Dlatego w przypadku transakcji musisz podać cenę brutto lub netto, w zależności od sytuacji. Pobiera cenę brutto lub netto z ustawień wprowadzonych w zasadach rejestrowania transakcji.

Jeśli skonfigurujesz plan cennika, w którym obciążasz dewelopera za każdą transakcję, możesz ustawić stawkę dla planu na podstawie atrybutu niestandardowego, takiego jak liczba bajtów przesłanych w transakcji. Funkcje zarabiania muszą wiedzieć, czym jest atrybut niestandardowy i gdzie go znaleźć. Dlatego musisz określić atrybut niestandardowy w zasadach rejestrowania transakcji.

Oprócz określania atrybutów transakcji w zasadach rejestrowania transakcji możesz też określić kryteria powodzenia transakcji, aby ustalić, kiedy transakcja jest uznawana za zakończoną sukcesem (na potrzeby naliczania opłat). Przykłady ustawiania kryteriów sukcesu transakcji znajdziesz w artykule Przykłady ustawiania kryteriów sukcesu transakcji w zasadach dotyczących rejestrowania transakcji. Możesz też określić atrybuty niestandardowe usługi API (na podstawie których naliczane są opłaty za plan taryfowy).

Konfigurowanie zasad rejestrowania transakcji

Otwórz stronę Zestawy produktów zgodnie z poniższym opisem.

Konfigurowanie atrybutów transakcji

W sekcji Atrybuty transakcji określ kryteria, które wskazują na pomyślną transakcję generującą przychody.

1. W polu Kryteria powodzenia transakcji określ wyrażenie na podstawie wartości atrybutu Stan (opisanego dalej), aby określić, kiedy transakcja jest zakończona (na potrzeby naliczania opłat). Transakcje, które nie zostały zrealizowane (tzn. nie spełniają kryteriów w wyrażeniu), są rejestrowane, ale nie są do nich stosowane plany cenowe. Na przykład:

   txProviderStatus == 'OK'

2. Atrybut Status zawiera wartość używaną przez wyrażenie skonfigurowane w polu Kryteria powodzenia transakcji. Skonfiguruj atrybut Stan, definiując te pola:

   Pole	Opis
   Zasób interfejsu API	Wzorce URI zdefiniowane w produkcie API, które będą używane do identyfikowania transakcji generujących przychody.
   Lokalizacja odpowiedzi	Lokalizacja odpowiedzi, w której określony jest atrybut. Prawidłowe wartości to: Zmienna przepływu, Nagłówek, Treść JSON i Treść XML.
   Wartość	Wartość odpowiedzi. Aby podać więcej niż 1 wartość, kliknij + Dodaj x (np. + Dodaj zmienną przepływu).

3. Aby skonfigurować opcjonalne atrybuty transakcji, włącz przełącznik Używaj atrybutów opcjonalnych i skonfiguruj dowolne atrybuty transakcji zdefiniowane w tabeli poniżej.

   Atrybut	Opis
   Cena brutto	Ten atrybut ma zastosowanie tylko w przypadku planów cenowych, które korzystają z modelu podziału przychodów. W przypadku tych planów cenowych wymagana jest cena brutto lub cena netto. Upewnij się, że wartość liczbowa jest wyrażona jako typ String. Cena brutto transakcji. W przypadku planów z udziałem w przychodach musisz zarejestrować atrybut cena brutto lub cena netto. Wymagany atrybut zależy od podstawy udziału w przychodach. Możesz na przykład skonfigurować plan podziału przychodów na podstawie ceny brutto transakcji. W takim przypadku pole Cena brutto jest wymagane.
   Cena ostateczna	Ten atrybut ma zastosowanie tylko w przypadku planów cenowych, które korzystają z modelu podziału przychodów. W przypadku tych planów cenowych wymagana jest cena brutto lub cena netto. Upewnij się, że wartość liczbowa jest wyrażona jako typ String. Cena netto transakcji. W przypadku planów z udziałem w przychodach musisz zarejestrować pole Cena netto lub Cena brutto. Wymagane pole zależy od podstawy udziału w przychodach. Możesz na przykład skonfigurować plan podziału przychodów na podstawie ceny netto transakcji. W takim przypadku pole Cena netto jest wymagane.
   Waluta	Ten atrybut jest wymagany w przypadku planów cenowych, które korzystają z modelu podziału przychodów. Rodzaj waluty, której dotyczy transakcja.
   Kod błędu	Kod błędu powiązany z transakcją. Zawiera dodatkowe informacje o nieudanej transakcji.
   Opis produktu	Opis transakcji.
   Podatek	Ten atrybut jest istotny tylko w przypadku modeli dzielenia się przychodami i tylko wtedy, gdy kwota podatku jest rejestrowana w wywołaniach interfejsu API. Upewnij się, że wartość liczbowa jest wyrażona jako typ String. Kwota podatku od zakupu. Cena netto plus podatek = cena brutto.

Na przykład ustawiając te wartości, funkcja zarabiania otrzymuje wartość zmiennej przepływu z odpowiedzi na wiadomość w zmiennej o nazwie response.reason.phrase. Jeśli wartość to OK, a do żądania ProxyEndpoint w proxy interfejsu API dołączona jest zasada sprawdzania limitów zarabiania, zarabianie traktuje to jako transakcję.

Konfigurowanie atrybutów niestandardowych

W sekcji Atrybuty niestandardowe możesz określić atrybuty niestandardowe, które mają być uwzględnione w zasadach rejestrowania transakcji. Jeśli na przykład skonfigurujesz abonament z cennikiem, w którym obciążasz dewelopera za każdą transakcję, możesz ustawić stawkę abonamentu na podstawie atrybutu niestandardowego, takiego jak liczba bajtów przesłanych w transakcji. Następnie musisz uwzględnić ten atrybut niestandardowy w zasadach rejestrowania transakcji.

Każdy z tych atrybutów jest przechowywany w dzienniku transakcji, o który możesz wysyłać zapytania. Wyświetlają się one również podczas tworzenia planu cenowego (aby można było wybrać co najmniej 1 z tych atrybutów, na którym będzie opierać się cena planu).

W raportach podsumowujących przychody możesz uwzględniać atrybuty niestandardowe zdefiniowane w zasadach rejestrowania transakcji, zgodnie z opisem w artykule Uwzględnianie w raportach podsumowujących przychody atrybutów transakcji niestandardowych.

Aby skonfigurować atrybuty niestandardowe, włącz przełącznik Używaj atrybutów niestandardowych i określ maksymalnie 10 atrybutów niestandardowych. W przypadku każdego atrybutu niestandardowego uwzględnionego w zasadach rejestrowania transakcji musisz podać te informacje:

Łączenie zasobów z unikalnym identyfikatorem transakcji

Niektóre transakcje są proste i obejmują wywołanie interfejsu API do jednego zasobu. Inne transakcje mogą być jednak bardziej złożone. Załóżmy na przykład, że transakcja zakupu produktu w aplikacji w grze mobilnej obejmuje kilka wywołań zasobów:

• Wywołanie interfejsu API rezerwacji, które zapewnia, że użytkownik korzystający z abonamentu przedpłaconego ma wystarczającą ilość środków na zakup produktu, i przydziela („rezerwuje”) środki na zakup.
• Wywołanie interfejsu API do obciążania, które powoduje odjęcie środków z konta użytkownika korzystającego z przedpłaty.

Aby przetworzyć całą transakcję, platforma do zarabiania musi mieć możliwość powiązania pierwszego zasobu (wywołania i odpowiedzi do i z interfejsu Reserve API) z drugim zasobem (wywołania i odpowiedzi do i z interfejsu Charge API). W tym celu korzysta z informacji podanych w sekcji Łączenie zasobów z unikalnym identyfikatorem transakcji.

Aby skonfigurować atrybuty niestandardowe, włącz przełącznik Używaj unikalnych identyfikatorów transakcji i połącz transakcje. W przypadku każdej transakcji określasz zasób, lokalizację odpowiedzi i wartość atrybutu, które są powiązane z odpowiednimi wartościami w innych transakcjach.

Załóżmy na przykład, że wywołanie interfejsu API rezerwacji i wywołanie interfejsu API obciążenia są połączone w ten sposób: pole o nazwie session_id w nagłówku odpowiedzi z interfejsu API rezerwacji odpowiada nagłówkowi odpowiedzi o nazwie reference_id z interfejsu API obciążenia. W takim przypadku możesz ustawić wpisy w sekcji Łączenie zasobów z unikalnym identyfikatorem transakcji w ten sposób:

Konfigurowanie zwrotów środków

W sekcji Zwroty środków określasz atrybuty, których używa funkcja zarabiania do przetwarzania zwrotów środków.

Załóżmy na przykład, że użytkownik kupuje produkt w aplikacji mobilnej, która korzysta z Twoich interfejsów API generujących przychody. Transakcja jest spieniężana na podstawie planu wspólnego udziału w przychodach. Załóżmy jednak, że użytkownik nie jest zadowolony z produktu i chce go zwrócić. Jeśli zwrot środków za produkt nastąpi w wyniku wywołania interfejsu API, który realizuje zwrot, system zarabiania wprowadzi niezbędne zmiany w zarabianiu. Odbywa się to na podstawie informacji podanych w sekcji Zwroty w zasadach rejestrowania transakcji.

Aby skonfigurować zwroty środków, włącz przełącznik Użyj atrybutów zwrotu środków i określ szczegóły zwrotu:

1. Określ kryteria zwrotu środków, wypełniając te pola:

   Pole	Opis
   Lokalizacja odpowiedzi	Zasób transakcji zwrotu środków. Jeśli produkt interfejsu API udostępnia wiele zasobów, możesz wybrać tylko ten, który umożliwia zwrot środków.
   Kryteria zrealizowania zwrotu środków	Wyrażenie oparte na wartości atrybutu Stan (opisanego dalej), które określa, kiedy transakcja zwrotu środków jest zakończona (na potrzeby obciążenia). Nieudane transakcje zwrotu środków (czyli takie, które nie spełniają kryteriów w wyrażeniu) są rejestrowane, ale nie są do nich stosowane plany cenowe. Na przykład: txProviderStatus == 'OK'

2. Skonfiguruj atrybut Stan, definiując te pola:

   Pole	Opis
   Lokalizacja odpowiedzi	Lokalizacja odpowiedzi, w której określony jest atrybut. Prawidłowe wartości to: Zmienna przepływu, Nagłówek, Treść JSON i Treść XML.
   Wartość	Wartość odpowiedzi. Aby podać więcej niż 1 wartość, kliknij + Dodaj x (np. + Dodaj zmienną przepływu).

3. Skonfiguruj atrybut Identyfikator elementu nadrzędnego, określając te pola:

   Pole	Opis
   Lokalizacja odpowiedzi	Lokalizacja odpowiedzi, w której określony jest atrybut. Prawidłowe wartości to: Zmienna przepływu, Nagłówek, Treść JSON i Treść XML.
   Wartość	Identyfikator transakcji, za którą przetwarzany jest zwrot środków. Jeśli na przykład użytkownik kupi produkt, a potem poprosi o zwrot środków, identyfikator transakcji nadrzędnej będzie identyfikatorem transakcji zakupu. Aby podać więcej niż 1 wartość, kliknij + Dodaj x (np. + Dodaj zmienną przepływu).

4. Aby skonfigurować opcjonalne atrybuty zwrotu środków, włącz przełącznik Use Optional Refund Attributes (Użyj opcjonalnych atrybutów zwrotu środków) i skonfiguruj atrybuty. Opcjonalne atrybuty zwrotu środków są takie same jak opcjonalne atrybuty transakcji, zgodnie z definicją w sekcji Konfigurowanie atrybutów transakcji.

Zarządzanie zasadami rejestrowania transakcji za pomocą interfejsu API

W kolejnych sekcjach opisujemy, jak zarządzać zasadami rejestrowania transakcji za pomocą interfejsu API.

Tworzenie zasady rejestrowania transakcji za pomocą interfejsu API

Zasady rejestrowania transakcji określasz jako atrybut usługi API. Wartość atrybutu określa:

• Sufiks URI zasobu produktu, do którego dołączone są zasady rejestrowania transakcji. Sufiks zawiera zmienną wzorca ujętą w nawiasy klamrowe. Zmienna pattern jest oceniana przez usługi API w czasie działania. Na przykład ten sufiks URI zawiera zmienną wzorca {id}.

  /reserve/{id}**

  W tym przypadku usługi API oceniają sufiks URI zasobu jako /reserve, po którym następuje dowolny podkatalog zaczynający się od identyfikatora zdefiniowanego przez dostawcę interfejsu API.

• Zasób w odpowiedzi, do którego jest dołączony. Produkt interfejsu API może mieć wiele zasobów, a każdy z nich może mieć dołączoną zasadę rejestrowania transakcji w odpowiedzi z tego zasobu.
• Zasady wyodrębniania zmiennych, które umożliwiają zasadom rejestrowania transakcji wyodrębnianie treści z wiadomości z odpowiedzią w przypadku parametrów transakcji, które chcesz rejestrować.

Atrybut zasady rejestrowania transakcji dodajesz do usługi API, wysyłając żądanie PUT do interfejsu Management API https://api.enterprise.apigee.com/v1/organizations/{org_name}/apiproducts/{apiproduct_Id} (a nie do interfejsu Monetization API).

Określanie kryteriów sukcesu transakcji za pomocą interfejsu API

Możesz określić kryteria powodzenia transakcji, aby określić, kiedy transakcja jest udana (na potrzeby naliczania opłat). Transakcje, które nie zostały zrealizowane (czyli spełniają kryteria w wyrażeniu), są rejestrowane, ale nie są do nich stosowane plany cenowe. Przykłady ustawiania kryteriów sukcesu transakcji znajdziesz w artykule Przykłady ustawiania kryteriów sukcesu transakcji w zasadach rejestrowania transakcji.

Kryteria sukcesu transakcji określasz jako atrybut usługi API. Aby to zrobić, wyślij żądanie PUT do interfejsu Management APIhttps://api.enterprise.apigee.com/v1/organizations/{org_name}/apiproducts/{apiproduct_Id} (a nie do interfejsu Monetization API).

Na przykład w tym żądaniu transakcja jest uznawana za zrealizowaną, jeśli wartość parametru txProviderStatus to success (specyfikacje związane z kryteriami powodzenia transakcji są wyróżnione).

$ 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

Określanie atrybutów niestandardowych za pomocą interfejsu API

Możesz określić atrybuty niestandardowe usługi API, na podstawie których naliczane są opłaty za plan taryfowy. Jeśli na przykład skonfigurujesz plan cennika, w którym obciążasz dewelopera za każdą transakcję, możesz ustawić stawkę dla planu na podstawie atrybutu niestandardowego, takiego jak liczba bajtów przesłanych w transakcji. Podczas tworzenia abonamentu możesz określić co najmniej 1 atrybut niestandardowy, na którym będzie oparta cena abonamentu. Jednak każdy konkretny produkt w ramach planu cenowego może mieć tylko 1 atrybut niestandardowy, na którym będzie oparta cena planu.

Atrybuty niestandardowe określa się jako atrybuty usługi API. Aby to zrobić, wyślij żądanie PUT do interfejsu Management APIhttps://api.enterprise.apigee.com/v1/organizations/{org_name}/apiproducts/{apiproduct_Id} (a nie do interfejsu Monetization API).

W przypadku każdego atrybutu niestandardowego dodawanego do produktu interfejsu API musisz podać nazwę i wartość atrybutu. Nazwa musi mieć format MINT_CUSTOM_ATTRIBUTE_{num}, gdzie {num} to liczba całkowita.

Na przykład to żądanie określa 3 atrybuty niestandardowe.

$ 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

Przykłady ustawiania kryteriów sukcesu transakcji w zasadach nagrywania transakcji

W tabeli poniżej znajdziesz przykłady udanych i nieudanych transakcji na podstawie wyrażenia kryteriów sukcesu transakcji i wartości txProviderStatus zwracanej przez serwer proxy interfejsu API. txProviderStatus to zmienna wewnętrzna, której funkcja zarabiania używa do określania, czy transakcja zakończyła się sukcesem.