Konfigurowanie zasad rejestrowania transakcji

Przeglądasz dokumentację Apigee Edge.
Otwórz dokumentację Apigee X. Informacje

Skonfiguruj zasady rejestrowania transakcji dla każdej usługi API w pakiecie API zgodnie z opisem w kolejnych sekcjach.

Wstęp

Zasada rejestrowania transakcji pozwala na rejestrowanie parametrów transakcji i atrybutów niestandardowych. Funkcja zarabiania wymaga tych informacji do przetwarzania przychodu, np. do stosowania planów taryfowych.

Jeśli na przykład skonfigurujesz plan stawek udziału w przychodach, procent przychodów wygenerowanych w każdej transakcji z użyciem usługi API generującej przychody będzie dzielony deweloperowi aplikacji, która wysłała żądanie. Udział w przychodach jest obliczany na podstawie ceny netto lub brutto transakcji (którą określasz samodzielnie), czyli procent wartości brutto lub ceny netto z każdej transakcji służy do określenia udziału w przychodach. Z tego powodu funkcja zarabiania musi znać cenę brutto lub netto transakcji. Wykorzystuje ona cenę brutto lub netto z ustawień wybranych w zasadach rejestrowania transakcji.

Jeśli skonfigurujesz plan w arkuszu stawek, w którym obciążasz dewelopera za każdą transakcję, możesz ustawić stawkę dla abonamentu na podstawie atrybutu niestandardowego, na przykład liczby bajtów przesłanych w transakcji. Funkcja Generowanie przychodu musi wiedzieć, co to jest atrybut niestandardowy i gdzie go znaleźć. Musisz więc określić atrybut niestandardowy w zasadzie rejestrowania transakcji.

Oprócz określenia atrybutów transakcji w zasadzie rejestrowania transakcji możesz też określić kryteria sukcesu transakcji, aby określić, kiedy transakcja została zrealizowana (na potrzeby opłat). Przykłady ustawiania kryteriów powodzenia transakcji znajdziesz w artykule Przykłady ustawiania kryteriów powodzenia transakcji w zasadach rejestrowania transakcji. Możesz też określić atrybuty niestandardowe usługi API (w której są naliczane opłaty za abonament podstawowy).

Konfigurowanie zasady rejestrowania transakcji

Otwórz stronę Pakiety produktów w sposób opisany poniżej.

Konfigurowanie atrybutów transakcji

W sekcji Atrybuty transakcji określ kryteria pomyślnej transakcji zarabiania.

1. W polu Kryteria transakcji podaj wyrażenie na podstawie wartości atrybutu Stan (opisanego poniżej) w celu określenia, czy transakcja została zrealizowana (na potrzeby obciążeń). Transakcje, które nie zostaną zrealizowane (czyli nie spełniają kryteriów tego wyrażenia), są rejestrowane, ale plany stawek nie są do nich stosowane. Na przykład:

   txProviderStatus == 'OK'

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

   Field	Opis
   Zasób API	Wzorce identyfikatorów URI zdefiniowane w usłudze API, które zostaną użyte do identyfikowania transakcji generujących przychody.
   Lokalizacja odpowiedzi	Lokalizacja odpowiedzi, w której określono atrybut. Prawidłowe wartości to: Zmienna przepływu, Nagłówek, Treść JSON i Treść XML.
   Wartość	Wartość odpowiedzi. Aby podać więcej niż jedną wartość, kliknij + Dodaj x (np. + Dodaj zmienną przepływu).

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

   Atrybut	Opis
   Cena brutto	Ten atrybut ma zastosowanie tylko do planów stawek korzystających z modelu udziału w przychodach. W przypadku takich planów musisz podać cenę brutto lub cenę netto. Upewnij się, że wartość liczbowa jest wyrażona jako ciąg znaków. Cena brutto transakcji. W przypadku planów związanych z udziałem w przychodach musisz zarejestrować atrybut Cena brutto lub cena netto. Wymagany atrybut zależy od udziału w przychodach. Możesz na przykład skonfigurować plan udziału w przychodach, który jest oparty na cenie brutto transakcji. W takim przypadku wymagane jest pole Cena brutto.
   Cena ostateczna	Ten atrybut ma zastosowanie tylko do planów stawek korzystających z modelu udziału w przychodach. W przypadku takich planów musisz podać cenę brutto lub cenę netto. Upewnij się, że wartość liczbowa jest wyrażona jako ciąg znaków. Cena netto transakcji. W przypadku planów związanych z udziałem w przychodach musisz uwzględnić pole Cena netto lub cena brutto. To, które pole należy wypełnić, zależy od udziału w przychodach. Możesz na przykład skonfigurować plan stawki udziału w przychodach, który jest oparty na cenie netto transakcji. W takim przypadku musisz wypełnić pole Cena netto.
   Waluta	Ten atrybut jest wymagany w przypadku planów stawek korzystających z modelu udziału w przychodach. Rodzaj waluty, która dotyczy transakcji.
   Kod błędu	Kod błędu powiązany z transakcją. Zawiera dodatkowe informacje o nieudanej transakcji.
   Opis produktu	Opis transakcji.
   Podatek	Ten atrybut ma zastosowanie tylko w przypadku modeli udziału w przychodach i tylko wtedy, gdy kwota podatku jest rejestrowana w wywołaniach interfejsu API. Upewnij się, że wartość liczbowa jest wyrażona jako typ ciągu znaków. Kwota podatku od zakupu. Cena netto plus podatek = cena brutto.

Na przykład: ustawiając poniższe wartości, przychody otrzymują wartość zmiennej przepływu z odpowiedzi na wiadomość w zmiennej o nazwie response.reason.phrase. Jeśli wartość jest prawidłowa, a do żądania ProxyEndpoint interfejsu API do interfejsu API jest dołączona zasada sprawdzania limitów zarabiania, funkcja zarabiania policzy transakcję jako transakcję.

Field	Wartość
Kryteria udanej transakcji	txProviderStatus == 'OK'
Stan: zasób API	**
Stan: lokalizacja odpowiedzi	Zmienna przepływu
Stan: Zmienna przepływu	response.reason.phrase

Konfigurowanie atrybutów niestandardowych

W sekcji Atrybuty niestandardowe wskazujesz atrybuty niestandardowe, które chcesz uwzględnić w zasadzie rejestrowania transakcji. Jeśli na przykład skonfigurujesz plan w arkuszu stawek, w którym obciążasz dewelopera za każdą transakcję, możesz ustawić stawkę dla abonamentu na podstawie atrybutu niestandardowego, takiego jak liczba bajtów przesłanych w transakcji. Musisz wtedy uwzględnić ten atrybut niestandardowy w zasadzie rejestrowania transakcji.

Każdy z tych atrybutów jest przechowywany w dzienniku transakcji, do którego możesz wysyłać zapytania. Są one też wyświetlane podczas tworzenia abonamentu (dzięki czemu możesz wybrać co najmniej 1 z tych atrybutów, na podstawie których będzie podstawa Twoja stawka w abonamencie).

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

Aby skonfigurować atrybuty niestandardowe, włącz przełącznik Użyj atrybutów niestandardowych i zdefiniuj maksymalnie 10 atrybutów niestandardowych. Dla każdego atrybutu niestandardowego uwzględnionego w zasadzie rejestrowania transakcji musisz podać te informacje.

Field	Opis
Nazwa niestandardowego atrybutu	Wpisz nazwę opisującą atrybut niestandardowy. Jeśli abonament jest oparty na atrybucie niestandardowym, ta nazwa będzie wyświetlana użytkownikowi w szczegółach abonamentu. Jeśli na przykład atrybut niestandardowy przechwytuje czas trwania, należy nazwać jego czas trwania. Rzeczywiste jednostki dla atrybutu niestandardowego (np. godziny, minuty lub sekundy) są ustawiane w polu jednostki oceny podczas tworzenia planu stawki atrybutu niestandardowego (zobacz Określanie planu stawek za pomocą szczegółów atrybutów niestandardowych).
Zasób API	Wybierz co najmniej 1 sufiks URI (czyli fragment identyfikatora URI po ścieżce podstawowej) zasobu API, do którego uzyskiwany jest dostęp w transakcji. Dostępne zasoby są takie same jak w przypadku atrybutów transakcji.
Lokalizacja odpowiedzi	Wybierz lokalizację w odpowiedzi, w której określono atrybut. Prawidłowe wartości to: Zmienna przepływu, Nagłówek, Treść JSON i Treść XML.
Wartość	Podaj wartość atrybutu niestandardowego. Każda podana wartość odpowiada polu, parametrowi lub elementowi treści, który dostarcza atrybut niestandardowy w podanej przez Ciebie lokalizacji. Aby podać więcej niż jedną wartość, kliknij + Dodaj x (np. + Dodaj zmienną przepływu). Jeśli na przykład skonfigurujesz atrybut niestandardowy o nazwie Długość treści i wybierzesz Nagłówek jako lokalizację odpowiedzi, to jeżeli w polu Długość treści HTTP zostanie podana wartość Długość treści, jako tę wartość podasz Content-Length.

Połącz zasoby z unikalnym identyfikatorem transakcji

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

• Wywołanie interfejsu API Reserve, które daje pewność, że użytkownik z góry ma wystarczające środki na zakup produktu i przydziela („rezerwuje”) środki na ten zakup.
• Wywołanie interfejsu API obciążenia, które powoduje odliczenie środków z konta przedpłaconego użytkownika.

Aby przetworzyć całą transakcję, funkcja zarabiania musi łączyć pierwszy zasób (wywołanie i odpowiedź z interfejsu Reserve API oraz odpowiedź z niego) z drugim (wywołaniem i odpowiedzią na żądanie interfejsu Charge API oraz z niego). Aby to zrobić, korzysta z informacji podanych w sekcji Połącz zasoby z unikalnym identyfikatorem transakcji.

Aby skonfigurować atrybuty niestandardowe, włącz przełącznik Użyj 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ą połączone z odpowiednimi wartościami w innych transakcjach.

Załóżmy na przykład, że wywołanie interfejsu Reserve API i wywołanie interfejsu API opłat są połączone w następujący sposób: pole o nazwie session_id w nagłówku odpowiedzi interfejsu Reserve API odpowiada nagłówkowi odpowiedzi o nazwie reference_id z interfejsu Charge API. W takim przypadku możesz ustawić wpisy w sekcji Połącz zasoby z unikalnym identyfikatorem transakcji w następujący sposób:

Zasób	Lokalizacja odpowiedzi	Wartość
reserve/{id}**	Nagłówek	session_id
/charge/{id}**	Nagłówek	reference_id

Konfigurowanie zwrotów środków

W sekcji Zwroty środków podajesz atrybuty wykorzystywane przez funkcję zarabiania do przetwarzania zwrotów środków.

Załóżmy np., że użytkownik kupuje produkt w aplikacji mobilnej, która korzysta z interfejsów API generujących przychody. Transakcja będzie generować przychody zgodnie z planem dzielenia przychodów. Załóżmy jednak, że użytkownik jest niezadowolony z produktu i chce go zwrócić. Jeśli środki za produkt zostaną zwrócone za pomocą wywołania interfejsu API, które zwraca środki, w ramach zarabiania zostaną wprowadzone niezbędne korekty zarabiania. Dzieje się tak na podstawie informacji podanych w sekcji Zwroty środków 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 środków:

1. Kryteria zwrotu środków określ w tych polach:

   Field	Opis
   Lokalizacja odpowiedzi	Zasób dotyczący transakcji zwrotu środków. Jeśli usługa API ma wiele zasobów, możesz wybrać tylko ten, który wykona zwrot środków.
   Kryteria udanego zwrotu środków	Wyrażenie oparte na wartości atrybutu Stan (opisanego poniżej) w celu określenia, kiedy transakcja zwrotu środków została zrealizowana (na potrzeby obciążeń). Transakcje zwrotu środków, które nie zostaną zrealizowane (czyli nie spełniają podanych tu kryteriów), są rejestrowane, ale plany stawek nie są do nich stosowane. Na przykład: txProviderStatus == 'OK'

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

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

3. Skonfiguruj atrybut Identyfikator nadrzędny, definiując te pola:

   Field	Opis
   Lokalizacja odpowiedzi	Lokalizacja odpowiedzi, w której określono atrybut. Prawidłowe wartości to: Zmienna przepływu, Nagłówek, Treść JSON i Treść XML.
   Wartość	Identyfikator transakcji, w której przypadku przetwarzany jest zwrot środków. Jeśli np. 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ż jedną wartość, kliknij + Dodaj x (np. + Dodaj zmienną przepływu).

4. Aby skonfigurować opcjonalne atrybuty zwrotu środków, włącz przełącznik Użyj opcjonalnych atrybutów zwrotu środków i skonfiguruj atrybuty. Opcjonalne atrybuty zwrotu środków są takie same jak opcjonalne atrybuty transakcji określone w artykule Konfigurowanie atrybutów transakcji.

Zarządzanie zasadami rejestrowania transakcji za pomocą interfejsu API

Poniżej opisujemy, jak zarządzać zasadami rejestrowania transakcji za pomocą interfejsu API.

Tworzenie zasad rejestrowania transakcji przy użyciu interfejsu API

Zasady rejestrowania transakcji określasz jako atrybut produktu API. Wartość atrybutu identyfikuje:

• Sufiks identyfikatora URI zasobu produktu, do którego dołączone są zasady rejestrowania transakcji. Sufiks zawiera zmienną wzorca ujętą w nawiasy klamrowe. Zmienna wzorca jest oceniana przez usługi interfejsu API w czasie działania. Na przykład ten sufiks identyfikatora 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, który zaczyna się od identyfikatora zdefiniowanego przez dostawcę interfejsu API.

• Zasób w odpowiedzi, do której jest dołączony. Usługa interfejsu API może mieć wiele zasobów, a do każdego zasobu może być dołączona zasada rejestrowania transakcji.
• Zasada wyodrębniania zmiennych, która umożliwia zasadzie rejestrowania transakcji wyodrębnianie treści z wiadomości z odpowiedzią na potrzeby parametrów transakcji, które chcesz przechwytywać.

Aby dodać atrybut zasad rejestrowania transakcji do usługi API, wyślij żądanie PUT do interfejsu API zarządzania https://api.enterprise.apigee.com/v1/organizations/{org_name}/apiproducts/{apiproduct_Id} (a nie do interfejsu API zarabiania).

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

Możesz określić kryteria powodzenia transakcji, aby określić, kiedy transakcja została zrealizowana (na potrzeby obciążeń). Transakcje, które nie zostaną zrealizowane (czyli spełniają kryteria tego wyrażenia), są rejestrowane, ale plany stawek nie są do nich stosowane. Przykłady ustawiania kryteriów powodzenia transakcji znajdziesz w artykule Przykłady ustawiania kryteriów powodzenia transakcji w zasadach rejestrowania transakcji.

Kryteria powodzenia transakcji określasz jako atrybut produktu API. Aby to zrobić, wyślij żądanie PUT do interfejsu API zarządzania https://api.enterprise.apigee.com/v1/organizations/{org_name}/apiproducts/{apiproduct_Id} (a nie do interfejsu Monetization API).

Na przykład w poniższym żądaniu transakcja została zrealizowana, jeśli wartość txProviderStatus wynosi success (wyróżnione są specyfikacje związane z kryteriami powodzenia transakcji).

$ 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 przy użyciu interfejsu API

Możesz określić atrybuty niestandardowe usługi interfejsu API, za którą naliczasz opłaty według abonamentu podstawowego. Jeśli na przykład skonfigurujesz plan w arkuszu stawek, w którym obciążasz dewelopera za każdą transakcję, możesz ustawić stawkę dla abonamentu 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 podstawie którego będziesz ustalać stawkę w abonamencie. Jednak każdy produkt w planie stawek może mieć tylko 1 atrybut niestandardowy, na podstawie którego będzie można obliczyć stawkę w ramach abonamentu.

Atrybuty niestandardowe określasz jako atrybuty produktu API. Aby to zrobić, wyślij żądanie PUT do interfejsu API zarządzania https://api.enterprise.apigee.com/v1/organizations/{org_name}/apiproducts/{apiproduct_Id} (a nie do interfejsu Monetization API).

Dla każdego atrybutu niestandardowego, który dodajesz do produktu za pomocą interfejsu API, musisz określić nazwę i wartość atrybutu. Nazwa musi mieć format MINT_CUSTOM_ATTRIBUTE_{num}, gdzie {num} jest liczbą całkowitą.

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 powodzenia transakcji w zasadzie rejestrowania transakcji

W tabeli poniżej znajdziesz przykłady udanych i nieudanych transakcji obliczonych na podstawie wyrażenia kryteriów powodzenia transakcji oraz wartości txProviderStatus zwróconej przez serwer proxy interfejsu API. txProviderStatus to zmienna wewnętrzna używana przez funkcję zarabiania do określania powodzenia transakcji.

Wyrażenie kryterium sukcesu	Wyrażenie jest prawidłowe?	Wartość txProviderStatus z serwera proxy interfejsu API	Wynik oceny
null	prawda	"200"	false
""	false	"200"	false
" "	false	"200"	false
"sdfsdfsdf"	false	"200"	false
"txProviderStatus =='100'"	prawda	"200"	false
"txProviderStatus =='200'"	prawda	"200"	prawda
"true"	prawda	"200"	prawda
"txProviderStatus=='OK' OR txProviderStatus=='Not Found' OR txProviderStatus=='Bad Request'"	prawda	"OK"	prawda
"txProviderStatus matches '(OK)|(Not Found)|(Bad Request)'"	prawda	"OK"	prawda
"txProviderStatus matches '(OK)|(Not Found)|(Bad Request)'"	prawda	"Not Found"	prawda
"txProviderStatus matches '(OK)|(Not Found)|(Bad Request)'"	prawda	"Bad Request"	prawda
"(txProviderStatus?:'') matches '(?i)(OK)|(Not Found)|(Bad Request)'"	prawda	"Bad Request"	prawda
"(txProviderStatus?:'') matches '(?i)(OK)|(Not Found)|(Bad Request)'"	prawda	null	false
"txProviderStatus matches '(?i)(OK)|(Not Found)|(Bad Request)'"	prawda	"bad request"	prawda
"txProviderStatus matches '(?i)(OK)|(Not Found)|(Bad Request)'"	prawda	"Redirect"	false
"txProviderStatus matches '(?i)(OK)|(Not Found)|(Bad Request)'"	prawda	"heeeelllooo"	false
"txProviderStatus matches '(?i)(OK)|(Not Found)|(Bad Request)'"	prawda	null	false
"txProviderStatus == 100"	prawda	"200"	false