Configurare un criterio di registrazione delle transazioni

Stai visualizzando la documentazione di Apigee Edge.
Vai alla documentazione di Apigee X.
informazioni

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

Introduzione

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

Ad esempio, se configuri un piano tariffario per la quota di condivisione delle entrate, una percentuale delle entrate generate da ogni transazione relativa al tuo prodotto API monetizzato viene condivisa con lo sviluppatore dell'app che ha inviato la richiesta. La quota di condivisione delle entrate si basa sul prezzo netto o lordo della transazione (devi specificare quale), 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. Recupera il prezzo lordo o netto dalle impostazioni specificate nelle norme di registrazione delle transazioni.

Se configuri un piano tariffario con cui addebiti allo sviluppatore per 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. Devi quindi specificare l'attributo personalizzato nella norma di registrazione delle transazioni.

Oltre a specificare gli attributi delle transazioni nelle norme di registrazione delle transazioni, puoi specificare i criteri di esito positivo delle transazioni per determinare quando una transazione va a buon fine (a fini di addebito). Per esempi sull'impostazione dei criteri di esito positivo delle transazioni, consulta la sezione Esempi di impostazione dei criteri di esito positivo delle transazioni in un criterio di registrazione delle transazioni. Puoi anche specificare attributi personalizzati per un prodotto API (su cui vengono addebitati i costi del piano tariffario di base).

Configurare un criterio di registrazione delle transazioni

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

Perimetrale

Quando aggiungi un pacchetto di prodotti API utilizzando l'interfaccia utente Edge, devi configurare il criterio di registrazione delle transazioni seguendo questi passaggi:

  1. Seleziona il prodotto API da configurare nella sezione Norme per la registrazione delle transazioni (se il pacchetto di prodotti contiene più prodotti API).
  2. Configura gli attributi delle transazioni.
  3. Configura gli attributi personalizzati.
  4. Collega le risorse con ID transazione univoci.
  5. Configura i rimborsi.
  6. Ripeti la procedura per ogni prodotto API definito nel pacchetto di prodotti API.

Classic Edge (private cloud)

Per configurare un criterio di registrazione delle transazioni utilizzando l'interfaccia utente classica di Edge:

  1. Accedi a http://ms-ip:9000, dove ms-ip è l'indirizzo IP o il nome DNS del nodo del server di gestione.
  2. Seleziona Pubblica > Prodotti nella barra di navigazione in alto.
  3. Fai clic su + Norme sulla registrazione delle transazioni nella riga del prodotto API applicabile. Viene visualizzata la finestra Nuova norma di registrazione delle transazioni.
  4. Per configurare il criterio di registrazione delle transazioni:
  5. Fai clic su Salva.

Configurazione degli attributi di transazione

Nella sezione Attributi delle transazioni, specifica i criteri che indicano una transazione di monetizzazione andata a buon fine.

  1. Nel campo Transaction Success Criteria, specifica l'espressione in base al valore dell'attributo Status (descritto di seguito) per determinare quando la transazione ha esito positivo (a fini di addebito). Le transazioni che non sono riuscite (ovvero non soddisfano i criteri dell'espressione) vengono registrate, ma non vengono applicati i piani tariffari. 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 risposta Posizione della risposta in cui è specificato l'attributo. I valori validi includono: Variabile di flusso, Intestazione, Corpo JSON e Corpo XML.
    Valore Valore della risposta. Per specificare più di un valore, fai clic su + Aggiungi x, ad esempio + Aggiungi variabile di flusso.
  3. Per configurare attributi facoltativi della transazione, abilita l'opzione di attivazione/disattivazione Utilizza attributi facoltativi e configura uno qualsiasi degli attributi della transazione definiti nella tabella seguente.
    Attributo Descrizione
    Prezzo lordo

    Questo attributo è applicabile solo per i piani tariffari che utilizzano il modello di quota di condivisione delle entrate. Per questi piani tariffari, il prezzo lordo o il prezzo netto è obbligatorio. Assicurati che il valore numerico sia espresso come tipo di stringa. Prezzo lordo di una transazione. Per i piani di quota di condivisione delle entrate, devi registrare l'attributo Prezzo lordo o Prezzo netto. L'attributo obbligatorio dipende dalla quota di condivisione delle entrate. Ad esempio, puoi configurare un piano tariffario relativo alla quota di condivisione delle entrate basato sul prezzo lordo di una transazione. In tal caso, il campo Prezzo lordo è obbligatorio.

    Prezzo netto

    Questo attributo è applicabile solo per i piani tariffari che utilizzano il modello di quota di condivisione delle entrate. Per questi piani tariffari, il prezzo lordo o il prezzo netto è obbligatorio. Assicurati che il valore numerico sia espresso come tipo di stringa. Prezzo netto di una transazione. Per i piani di quota di condivisione delle entrate, devi registrare il campo Prezzo netto o Prezzo lordo. Il campo obbligatorio dipende dalla quota di condivisione delle entrate. Ad esempio, puoi configurare un piano tariffario relativo alla quota di condivisione delle entrate basato sul prezzo netto di una transazione. In tal caso, il campo Prezzo netto è obbligatorio.

    Valuta

    Questo attributo è obbligatorio per i piani tariffari che utilizzano il modello di quota 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.

    Tasse

    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 di stringa. Importo delle imposte sull'acquisto. Prezzo netto più tasse = prezzo lordo.

Ad esempio, impostando i valori seguenti, la monetizzazione ottiene il valore della variabile di flusso dalla risposta al messaggio in una variabile chiamata response.reason.phrase. Se il valore è OK e le norme sul controllo dei limiti di monetizzazione sono allegate alla richiesta ProxyEndpoint del proxy API, la monetizzazione la conteggia come una transazione.

Campo Valore
Criteri di successo delle transazioni txProviderStatus == 'OK'
Stato: risorsa API **
Stato: posizione della risposta Variabile di flusso
Stato: variabile di flusso response.reason.phrase

Configurare attributi personalizzati

Nella sezione Attributi personalizzati, identifichi gli attributi personalizzati da includere nel criterio di registrazione delle transazioni. Ad esempio, se imposti un piano tariffario in cui addebiti allo sviluppatore ogni transazione, puoi impostare la tariffa del piano in base a un attributo personalizzato come il numero di byte trasmessi in una transazione. Devi quindi includere questo attributo personalizzato nelle norme di registrazione delle transazioni.

Ciascuno di questi attributi viene archiviato nel log delle transazioni, su cui puoi eseguire una query. Vengono visualizzati anche quando crei un piano tariffario (in modo da poter scegliere uno o più di questi attributi su cui basare la tariffa per il piano).

Puoi includere attributi personalizzati definiti nella norma di registrazione delle transazioni nei report di riepilogo delle entrate, come descritto in Inclusione di attributi personalizzati delle transazioni nei report di riepilogo delle entrate.

Per configurare attributi personalizzati, attiva l'opzione Utilizza attributi personalizzati e definisci fino a 10 attributi personalizzati. Per ogni attributo personalizzato che includi nel criterio di registrazione delle transazioni, devi specificare le seguenti informazioni.

Campo Descrizione
Nome attributo personalizzato Inserisci un nome che descriva l'attributo personalizzato. Se il piano tariffario si basa su un attributo personalizzato, questo nome viene mostrato all'utente nei dettagli del piano tariffario. Ad esempio, se l'attributo personalizzato acquisisce la durata, devi assegnare un nome alla durata dell'attributo. Le unità effettive per l'attributo personalizzato (ad esempio ore, minuti o secondi) vengono impostate nel campo dell'unità di valutazione quando crei un piano tariffario per l'attributo personalizzato (consulta la sezione Specificare il piano tariffario con i dettagli dell'attributo personalizzato).
Risorsa API Seleziona uno o più suffissi URI (ovvero il frammento URI che segue il percorso di base) di una risorsa API a cui si accede nella transazione. Le risorse disponibili sono le stesse degli attributi Transaction.
Posizione risposta Nella risposta, seleziona la località in cui è specificato l'attributo. I valori validi includono: Variabile di flusso, Intestazione, Corpo JSON e Corpo XML.
Valore Specifica un valore per l'attributo personalizzato. Ogni valore specificato corrisponde a un campo, parametro o elemento di contenuti che fornisce l'attributo personalizzato nella località specificata. Per specificare più di un valore, fai clic su + Aggiungi x, ad esempio + Aggiungi variabile di flusso.

Ad esempio, se configuri un attributo personalizzato denominato Lunghezza del contenuto e selezioni Intestazione come posizione della risposta, se nel campo Lunghezza contenuto HTTP viene specificato il valore Content-Length come valore.

Alcune transazioni sono semplici e richiedono 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 gioco per dispositivi mobili implichi 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 ("riserva") i fondi per l'acquisto.
  • Chiamata a un'API Charge che detrae i fondi dall'account dell'utente prepagato.

Per elaborare l'intera transazione, la monetizzazione richiede 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 che hai specificato nella sezione Collega risorse con ID transazione univoco.

Per configurare attributi personalizzati, attiva l'opzione Utilizza ID transazione univoci e collega le transazioni. Per ogni transazione, specifichi una risorsa, una località della risposta e un valore dell'attributo collegati ai valori corrispondenti nelle altre transazioni.

Ad esempio, supponiamo che la chiamata all'API Reserve e la chiamata API Charge siano collegate come segue: un campo denominato session_id nell'intestazione della risposta dell'API Reserve corrisponde a un'intestazione della risposta denominata reference_id dell'API Charge. In questo caso, potresti impostare le voci nella sezione Collega risorse con ID transazione univoco come segue:

Risorsa Località risposta Valore
reserve/{id}**

Titolo

session_id
/charge/{id}**

Titolo

reference_id

Configurazione dei rimborsi

Nella sezione Rimborsi, specifichi gli attributi utilizzati per la monetizzazione per elaborare i rimborsi.

Ad esempio, supponi che un utente acquisti un prodotto da un'app mobile che utilizza le tue API monetizzate. La transazione viene monetizzata in base al piano delle entrate condivise. 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 gli aggiustamenti necessari per la monetizzazione. Ciò avviene in base alle informazioni da te specificate nella sezione Rimborsi delle norme relative alla registrazione delle transazioni.

Per configurare i rimborsi, attiva l'opzione Utilizza attributi del rimborso e definisci i dettagli del rimborso:

  1. Definisci i criteri di rimborso definendo i seguenti campi:
    Campo Descrizione
    Posizione risposta Risorsa per la transazione di rimborso. Se il prodotto API fornisce più risorse, puoi selezionare solo quella che esegue il rimborso.
    Criteri di esito positivo del rimborso Espressione basata sul valore dell'attributo Status (descritto di seguito) per determinare quando la transazione di rimborso va a buon fine (a fini di addebito). Le transazioni di rimborso non andate a buon fine (ovvero non soddisfano i criteri dell'espressione) vengono registrate, ma non vengono applicati i piani tariffari. Ad esempio:

    txProviderStatus == 'OK'

  2. Configura l'attributo Stato definendo i seguenti campi:
    Campo Descrizione
    Posizione risposta Posizione della risposta in cui è specificato l'attributo. I valori validi includono: Variabile di flusso, Intestazione, Corpo JSON e Corpo XML.
    Valore 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 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 la quale 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 attributi facoltativi di rimborso, attiva l'opzione di attivazione/disattivazione Utilizza attributi di rimborso facoltativi e configura gli attributi. Gli attributi facoltativi refund sono gli stessi degli attributi facoltativi Transaction, così come definiti in Configurare gli attributi di transazione.

Gestione dei criteri di registrazione delle transazioni tramite l'API

Le seguenti sezioni descrivono come gestire i criteri di registrazione delle transazioni utilizzando l'API.

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

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

  • Il suffisso URI della risorsa di prodotto a cui è associato il criterio di registrazione delle transazioni. Il suffisso include una variabile pattern racchiusa tra parentesi graffe. La variabile pattern viene valutata dai servizi API in fase di runtime. Ad esempio, il seguente suffisso URI include la variabile pattern {id}.
    /reserve/{id}**
    

    In questo caso, i servizi API valutano 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 è collegato. Un prodotto API può avere più risorse e ogni risorsa può avere un criterio di registrazione delle transazioni associato a una risposta da quella risorsa.
  • Un criterio di estrazione della variabile che consente al criterio di registrazione delle transazioni di estrarre contenuti da un messaggio di risposta per i parametri della transazione che vuoi acquisire.

Per aggiungere l'attributo della norma di registrazione delle transazioni a un prodotto API, invii 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 esito positivo delle transazioni utilizzando l'API

Puoi specificare i criteri di esito positivo delle transazioni per determinare quando l'esito è positivo (ai fini dell'addebito). Le transazioni non riuscite (ovvero che soddisfano i criteri dell'espressione) vengono registrate, ma non vengono applicati i piani tariffari. Per esempi sull'impostazione dei criteri di esito positivo delle transazioni, consulta la pagina Esempi di impostazione dei criteri di esito positivo delle transazioni in un criterio di registrazione delle transazioni.

I criteri di successo delle transazioni vengono specificati 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 richiesta seguente una transazione ha esito positivo se il valore di txProviderStatus è success (sono evidenziate le specifiche relative ai criteri di successo delle transazioni).

$ 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 mediante l'API

Puoi specificare gli attributi personalizzati di un prodotto API su cui vengono addebitati i costi del piano base. Ad esempio, se configuri un piano tariffario in cui addebiti allo sviluppatore ogni transazione, puoi impostare la tariffa del piano in base a un attributo personalizzato come 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 per il piano. Tuttavia, qualsiasi prodotto specifico di un piano tariffario può avere un solo attributo personalizzato su cui basare la tariffa del piano.

Gli attributi personalizzati vengono specificati come attributi 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).

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 esito positivo delle transazioni in un criterio di registrazione delle transazioni

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

Espressione dei criteri di successo Espressione valida? Valore txProviderStatus dal proxy API Risultato della valutazione
null true "200" false
"" false "200" false
" " false "200" false
"sdfsdfsdf" false "200" false
"txProviderStatus =='100'" true "200" false
"txProviderStatus =='200'" true "200" true
"true" true "200" true
"txProviderStatus=='OK' OR
txProviderStatus=='Not Found' OR
txProviderStatus=='Bad Request'"
true "OK" true
"txProviderStatus matches '(OK)|(Not Found)|(Bad Request)'" true "OK" true
"txProviderStatus matches '(OK)|(Not Found)|(Bad Request)'" true "Not Found" true
"txProviderStatus matches '(OK)|(Not Found)|(Bad Request)'" true "Bad Request" true
"(txProviderStatus?:'') matches '(?i)(OK)|(Not Found)|(Bad Request)'" true "Bad Request" true
"(txProviderStatus?:'') matches '(?i)(OK)|(Not Found)|(Bad Request)'" true null false
"txProviderStatus matches '(?i)(OK)|(Not Found)|(Bad Request)'" true "bad request" true
"txProviderStatus matches '(?i)(OK)|(Not Found)|(Bad Request)'" true "Redirect" false
"txProviderStatus matches '(?i)(OK)|(Not Found)|(Bad Request)'" true "heeeelllooo" false
"txProviderStatus matches '(?i)(OK)|(Not Found)|(Bad Request)'" true null false
"txProviderStatus == 100" true "200" false