Configurare un criterio di registrazione delle transazioni

Stai visualizzando la documentazione di Apigee Edge.
Consulta la documentazione di Apigee X. info

Configura le norme di registrazione delle transazioni per ogni prodotto API nel bundle di prodotti API, come descritto nelle sezioni seguenti.

Introduzione

Una policy di registrazione delle transazioni consente alla monetizzazione di acquisire parametri delle transazioni e attributi personalizzati. La monetizzazione ha bisogno di queste informazioni per eseguire l'elaborazione della monetizzazione, ad esempio l'applicazione dei piani tariffari.

Ad esempio, se configuri un piano tariffario di condivisione delle entrate, una percentuale delle entrate generate da ogni transazione che coinvolge il tuo prodotto API monetizzato viene condivisa con lo sviluppatore dell'app che invia la richiesta. La quota di condivisione delle entrate si basa sul prezzo netto o lordo della transazione (specificato da te), ovvero una percentuale del prezzo lordo o netto di ogni transazione viene utilizzata per determinare la quota di condivisione delle entrate. Per questo motivo, la monetizzazione deve conoscere il prezzo lordo o netto di una transazione, a seconda dei casi. Ottiene il prezzo lordo o netto dalle impostazioni che effettui nel criterio di registrazione delle transazioni.

Se configuri un piano con tariffario, in cui addebiti allo sviluppatore ogni transazione, puoi impostare la tariffa del piano in base a un attributo personalizzato, ad esempio il numero di byte trasmessi in una transazione. La monetizzazione deve sapere cos'è l'attributo personalizzato e dove trovarlo. Pertanto, devi specificare l'attributo personalizzato nelle norme di registrazione delle transazioni.

Oltre a specificare gli attributi della transazione nelle norme di registrazione delle transazioni, puoi specificare i criteri di successo della transazione per determinare quando una transazione ha esito positivo (ai fini della fatturazione). Per esempi di impostazione dei criteri di successo delle transazioni, consulta Esempi di impostazione dei criteri di successo delle transazioni in un criterio di registrazione delle transazioni. Puoi anche specificare attributi personalizzati per un prodotto API (su cui basi gli addebiti del piano tariffario).

Configurazione di una policy di registrazione delle transazioni

Accedi alla pagina Pacchetti di prodotti, come descritto di seguito.

Configurazione degli attributi delle transazioni

Nella sezione Attributi transazione, specifica i criteri che indicano una transazione di monetizzazione riuscita.

1. Nel campo Criteri di riuscita della transazione, specifica l'espressione basata sul valore dell'attributo Stato (descritto di seguito) per determinare quando la transazione è riuscita (ai fini della fatturazione). Le transazioni non riuscite (ovvero che non soddisfano i criteri dell'espressione) vengono registrate, ma non vengono applicate le tariffe. Ad esempio:

   txProviderStatus == 'OK'

2. L'attributo Stato contiene il valore utilizzato dall'espressione configurata nel campo Criteri di successo della transazione. Configura l'attributo Stato definendo i seguenti campi:

   Campo	Descrizione
   Risorsa API	Pattern URI definiti nel prodotto API che verranno utilizzati per identificare le transazioni monetizzate.
   Posizione della risposta	Posizione della risposta in cui è specificato l'attributo. I valori validi includono: Variabile di flusso, Intestazione, Corpo JSON e Corpo XML.
   Valore	Il valore della risposta. Per specificare più di un valore, fai clic su + Aggiungi x (ad esempio, + Aggiungi variabile di flusso).

3. Per configurare gli attributi facoltativi delle transazioni, attiva il pulsante di attivazione/disattivazione Utilizza attributi facoltativi e configura uno qualsiasi degli attributi delle transazioni definiti nella tabella seguente.

   Attributo	Descrizione
   Prezzo lordo	Questo attributo è applicabile solo ai piani tariffari che utilizzano il modello di condivisione delle entrate. Per questi piani tariffari, è obbligatorio il prezzo lordo o il prezzo netto. Assicurati che il valore numerico sia espresso come tipo String. Prezzo lordo di una transazione. Per i piani di condivisione delle entrate, devi registrare l'attributo Prezzo lordo o l'attributo Prezzo netto. L'attributo richiesto dipende dalla base della quota di condivisione delle entrate. Ad esempio, puoi configurare un piano tariffario di condivisione delle entrate basato sul prezzo lordo di una transazione. In questo caso, il campo Prezzo lordo è obbligatorio.
   Prezzo netto	Questo attributo è applicabile solo ai piani tariffari che utilizzano il modello di condivisione delle entrate. Per questi piani tariffari, è obbligatorio il prezzo lordo o il prezzo netto. Assicurati che il valore numerico sia espresso come tipo String. Prezzo netto di una transazione. Per i piani di condivisione delle entrate, devi registrare il campo Prezzo netto o il campo Prezzo lordo. Il campo obbligatorio dipende dalla base della quota di condivisione delle entrate. Ad esempio, puoi configurare un piano di condivisione delle entrate basato sul prezzo netto di una transazione. In questo caso, il campo Prezzo netto è obbligatorio.
   Valuta	Questo attributo è obbligatorio per i piani tariffari che utilizzano il modello di condivisione delle entrate. Tipo di valuta applicabile alla transazione.
   Codice di errore	Codice di errore associato alla transazione. Fornisce ulteriori informazioni su una transazione non riuscita.
   Descrizione elemento	Descrizione della transazione.
   Imposta	Questo attributo è pertinente solo per i modelli di condivisione delle entrate e solo se l'importo delle tasse viene acquisito nelle chiamate API. Assicurati che il valore numerico sia espresso come tipo String. Importo delle imposte sull'acquisto. Prezzo netto più imposte = prezzo lordo.

Ad esempio, impostando i seguenti valori, la monetizzazione ottiene il valore della variabile di flusso dalla risposta del messaggio in una variabile denominata response.reason.phrase. Se il valore è OK e i criteri di controllo dei limiti di monetizzazione sono allegati alla richiesta ProxyEndpoint del proxy API, la monetizzazione lo considera una transazione.

Configurazione degli attributi personalizzati

Nella sezione Attributi personalizzati, identifica gli attributi personalizzati da includere nelle norme di registrazione delle transazioni. Ad esempio, se configuri un piano con tariffario, in cui addebiti allo sviluppatore ogni transazione, puoi impostare la tariffa per il piano in base a un attributo personalizzato, ad esempio il numero di byte trasmessi in una transazione. Dopodiché, devi includere l'attributo personalizzato nelle norme di registrazione delle transazioni.

Ciascuno di questi attributi viene memorizzato nel log delle transazioni, che puoi interrogare. Vengono visualizzati anche quando crei un piano tariffario (in modo da poter scegliere uno o più di questi attributi su cui basare la tariffa del piano).

Puoi includere gli attributi personalizzati definiti nelle norme di registrazione delle transazioni nei report di riepilogo delle entrate, come descritto in Includere attributi transazionali personalizzati nei report di riepilogo delle entrate.

Per configurare gli attributi personalizzati, attiva l'opzione Utilizza attributi personalizzati e definisci fino a 10 attributi personalizzati. Per ogni attributo personalizzato incluso nelle norme di registrazione delle transazioni, devi specificare le seguenti informazioni.

Collegare le risorse con un ID transazione univoco

Alcune transazioni sono semplici e prevedono una chiamata API a una risorsa. Tuttavia, altre transazioni possono essere più complesse. Ad esempio, supponiamo che una transazione per l'acquisto di un prodotto in-app in un'app di giochi mobile comporti più chiamate di risorse:

• Una chiamata a un'API di prenotazione che garantisce che un utente prepagato disponga di credito sufficiente per acquistare il prodotto e alloca ("prenota") i fondi per l'acquisto.
• Una chiamata a un'API di addebito che detrae i fondi dal conto dell'utente prepagato.

Per elaborare l'intera transazione, la monetizzazione ha bisogno di un modo per collegare la prima risorsa (la chiamata e la risposta da e verso l'API Reserve) con la seconda risorsa (la chiamata e la risposta da e verso l'API Charge). A questo scopo, si basa sulle informazioni specificate nella sezione Collega risorse con ID transazione univoco.

Per configurare gli attributi personalizzati, attiva l'opzione Utilizza ID transazione univoci e collega le transazioni. Per ogni transazione, specifica una risorsa, una posizione della risposta e un valore dell'attributo che è collegato ai valori corrispondenti nelle altre transazioni.

Ad esempio, supponiamo che la chiamata API di prenotazione e la chiamata API di addebito siano collegate nel seguente modo: un campo denominato session_id nell'intestazione della risposta dell'API di prenotazione corrisponde a un'intestazione della risposta denominata reference_id dell'API di addebito. In questo caso, puoi impostare le voci nella sezione Collega risorse con ID transazione univoco come segue:

Configurazione dei rimborsi

Nella sezione Rimborsi, specifica gli attributi che la monetizzazione utilizza per elaborare i rimborsi.

Ad esempio, supponiamo che un utente acquisti un prodotto da un'app mobile che utilizza le tue API monetizzate. La transazione viene monetizzata in base al piano di condivisione delle entrate. Tuttavia, supponiamo che l'utente non sia soddisfatto del prodotto e voglia restituirlo. Se il prodotto viene rimborsato utilizzando una chiamata alla tua API che esegue il rimborso, la monetizzazione apporta le modifiche necessarie. Lo fa in base alle informazioni specificate nella sezione Rimborsi delle norme di registrazione delle transazioni.

Per configurare i rimborsi, attiva il pulsante di attivazione/disattivazione Utilizza gli attributi di rimborso e definisci i dettagli del rimborso:

1. Definisci i criteri di rimborso definendo i seguenti campi:

   Campo	Descrizione
   Posizione della risposta	Risorsa per la transazione di rimborso. Se il prodotto API fornisce più risorse, puoi selezionare solo la risorsa che esegue il rimborso.
   Criteri di successo del rimborso	Espressione basata sul valore dell'attributo Stato (descritto di seguito) per determinare quando la transazione di rimborso va a buon fine (ai fini dell'addebito). Le transazioni di rimborso non riuscite (ovvero che non soddisfano i criteri dell'espressione) vengono registrate, ma non vengono applicate le tariffe. Ad esempio: txProviderStatus == 'OK'

2. Configura l'attributo Stato definendo i seguenti campi:

   Campo	Descrizione
   Posizione della risposta	Posizione della risposta in cui è specificato l'attributo. I valori validi includono: Variabile di flusso, Intestazione, Corpo JSON e Corpo XML.
   Valore	Il valore della risposta. Per specificare più di un valore, fai clic su + Aggiungi x (ad esempio, + Aggiungi variabile di flusso).

3. Configura l'attributo ID genitore definendo i seguenti campi:

   Campo	Descrizione
   Posizione della risposta	Posizione della risposta in cui è specificato l'attributo. I valori validi includono: Variabile di flusso, Intestazione, Corpo JSON e Corpo XML.
   Valore	ID della transazione per cui viene elaborato un rimborso. Ad esempio, se un utente acquista un prodotto e poi richiede un rimborso, l'ID transazione principale è l'ID della transazione di acquisto. Per specificare più di un valore, fai clic su + Aggiungi x (ad esempio, + Aggiungi variabile di flusso).

4. Per configurare gli attributi di rimborso facoltativi, attiva il pulsante di attivazione/disattivazione Utilizza attributi di rimborso facoltativi e configura gli attributi. Gli attributi di rimborso facoltativi sono gli stessi degli attributi di transazione facoltativi, come definiti in Configurazione degli attributi di transazione.

Gestione dei criteri di registrazione delle transazioni utilizzando l'API

Le sezioni seguenti descrivono come gestire le norme di registrazione delle transazioni utilizzando l'API.

Creazione di un criterio di registrazione delle transazioni utilizzando l'API

Specifichi una norma di registrazione delle transazioni come attributo di un prodotto API. Il valore dell'attributo identifica:

• Il suffisso URI della risorsa prodotto a cui è associata la norma di registrazione delle transazioni. Il suffisso include una variabile di pattern racchiusa tra parentesi graffe. La variabile pattern viene valutata da API Services in fase di runtime. Ad esempio, il seguente suffisso URI include la variabile di pattern {id}.

  /reserve/{id}**

  In questo caso, API Services valuta il suffisso URI della risorsa come /reserve seguito da qualsiasi sottodirectory che inizia con un ID definito dal provider dell'API.

• La risorsa nella risposta a cui è allegata. Un prodotto API può avere più risorse e a ogni risorsa può essere associata una policy di registrazione delle transazioni a una risposta di quella risorsa.
• Un criterio per le variabili di estrazione che consente al criterio di registrazione delle transazioni di estrarre contenuti da un messaggio di risposta per i parametri della transazione che vuoi acquisire.

Aggiungi l'attributo della norma di registrazione delle transazioni a un prodotto API inviando una richiesta PUT all'API di gestione https://api.enterprise.apigee.com/v1/organizations/{org_name}/apiproducts/{apiproduct_Id} (e non a un'API di monetizzazione).

Specificare i criteri di successo delle transazioni utilizzando l'API

Puoi specificare i criteri di successo della transazione per determinare quando una transazione ha esito positivo (ai fini della fatturazione). Le transazioni non riuscite (ovvero che soddisfano i criteri nell'espressione) vengono registrate, ma non vengono applicati piani tariffari. Per esempi di impostazione dei criteri di successo delle transazioni, vedi Esempi di impostazione dei criteri di successo delle transazioni in un criterio di registrazione delle transazioni.

Specifichi i criteri di successo della transazione come attributo di un prodotto API. Per farlo, invia una richiesta PUT all'API di gestione https://api.enterprise.apigee.com/v1/organizations/{org_name}/apiproducts/{apiproduct_Id} (e non all'API di monetizzazione).

Ad esempio, nella seguente richiesta una transazione ha esito positivo se il valore di txProviderStatus è success (le specifiche relative ai criteri di successo della transazione sono evidenziate).

$ 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

Specificare gli attributi personalizzati utilizzando l'API

Puoi specificare attributi personalizzati per un prodotto API su cui basare gli addebiti del piano tariffario. Ad esempio, se configuri un piano con tariffario, in cui addebiti allo sviluppatore ogni transazione, puoi impostare la tariffa per il piano in base a un attributo personalizzato, ad esempio il numero di byte trasmessi in una transazione. Quando crei un piano tariffario, puoi specificare uno o più attributi personalizzati su cui basare la tariffa del piano. Tuttavia, qualsiasi prodotto specifico in un piano tariffario può avere un solo attributo personalizzato su cui basare la tariffa del piano.

Specifichi gli attributi personalizzati come attributi di un prodotto API. A questo scopo, invia una richiesta PUT all'API di gestione https://api.enterprise.apigee.com/v1/organizations/{org_name}/apiproducts/{apiproduct_Id} (e non all'API di monetizzazione).

Per ogni attributo personalizzato che aggiungi a un prodotto API, devi specificare un nome e un valore dell'attributo. Il nome deve essere nel formato MINT_CUSTOM_ATTRIBUTE_{num}, dove {num} è un numero intero.

Ad esempio, la seguente richiesta specifica tre attributi personalizzati.

$ 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

Esempi di impostazione dei criteri di successo delle transazioni in una policy di registrazione delle transazioni

La tabella seguente fornisce esempi di transazioni riuscite e non riuscite, in base all'espressione dei criteri di riuscita della transazione e al valore txProviderStatus restituito dal proxy API. txProviderStatus è la variabile interna utilizzata dalla monetizzazione per determinare la riuscita della transazione.