Ampliare le risposte
Ridurre il numero di richieste all'API Stripe ampliando gli oggetti nelle risposte
Questa guida descrive come richiedere proprietà supplementari all’API. Imparerai a modificare le richieste in modo che le risposte includano:
- proprietà di oggetti correlati
- proprietà di oggetti con correlazione distante
- proprietà supplementari di tutti gli oggetti di un elenco
- le proprietà che non sono incluse per impostazione predefinita in una risposta
Come funziona
L’API Stripe è organizzata in risorse rappresentate da oggetti con proprietà di stato, configurazione e contesto. Tutti questi oggetti hanno ID univoci che è possibile utilizzare per recuperarli, aggiornarli ed eliminarli. L’API utilizza anche questi ID per collegare insieme gli oggetti correlati. Una sessione di checkout, ad esempio, si collega a un cliente tramite l 'ID cliente.
{ "id": "cs_test_KdjLtDPfAjT1gq374DMZ3rHmZ9OoSlGRhyz8yTypH76KpN4JXkQpD2G0", "object": "checkout.session", ... "customer": "cus_HQmikpKnGHkNwW", ... }
Qualora tu abbia bisogno di informazioni provenienti da un oggetto collegato, puoi recuperare tale oggetto in una nuova chiamata mediante il suo ID. Tuttavia, questo approccio richiede l’invio all’API di due richieste per accedere a un solo valore. Se hai bisogno di informazioni provenienti da più oggetti collegati, devi inviare una richiesta per ciascuno di essi, il che aumenta la latenza e la complessità dell’applicazione.
L’API offre la funzione Expand che consente di recuperare gli oggetti collegati in una singola chiamata, sostituendo l’ID dell’oggetto con tutti i suoi valori e le sue proprietà. Ad esempio, supponiamo che tu voglia accedere ai dettagli di un cliente associati a una determinata sessione di Checkout. Devi recuperare tale sessione e passare la proprietà customer alla matrice expand per indicare a Stripe di includere nella risposta l’intero oggetto Customer:
L’esempio sopra restituisce la sessione di Checkout con l’oggetto Customer completo anziché il suo ID:
{ "id": "cs_test_KdjLtDPfAjT1gq374DMZ3rHmZ9OoSlGRhyz8yTypH76KpN4JXkQpD2G0", "object": "checkout.session", ... "customer": { "id": "cus_HQmikpKnGHkNwW", "object": "customer", ... "metadata": { "user_id": "user_xyz" }, ... } }
Nota
Non tutte le proprietà possono essere ampliate. La documentazione di riferimento dell’API contrassegna le proprietà che possono esserlo con l’etichetta “Ampliabile”.
Ampliare più proprietà
Per ampliare più proprietà in una sola chiamata, aggiungi elementi supplementari alla matrice Expand. Ad esempio, per ampliare entrambi gli oggetti customer e payment_intent per una determinata sessione di Checkout, devi passare alla matrice expand entrambe le stringhe customer e payment_:
Ampliare più livelli
Se il valore desiderato è nidificato in profondità in più risorse collegate, puoi raggiungerlo mediante ampliamento ricorsivo utilizzando la notazione con punto. Ad esempio, se vuoi conoscere il tipo di modalità di pagamento utilizzato per una determinata sessione di Checkout, devi prima recuperare il Payment Intent della sessione, quindi la modalità di pagamento ad esso collegata. Con expand puoi eseguire questa operazione in una sola chiamata:
L’esempio sopra restituisce la sessione di Checkout con gli oggetti PaymentIntent e PaymentMethod completi anziché i loro ID:
{ "id": "cs_test_KdjLtDPfAjT1gq374DMZ3rHmZ9OoSlGRhyz8yTypH76KpN4JXkQpD2G0", "object": "checkout.session", ... "mode": "payment", "payment_intent": { "id": "pi_1GkXXDLHughnNhxyLlsnvUuY", "object": "payment_intent", "amount": 100, ... "charges": {...}, "client_secret": "pi_1GkXXDLHughnNhxyLlsnvUuY_secret_oLbwpm0ME0ieJ9Aykz2SwKzj5", ... "payment_method": { "id": "pm_1GkXXuLHughnNhxy8xpAdGtf", "object": "payment_method", "billing_details": {...}, "card": {...},
Nota
Gli ampliamenti hanno una profondità massima di quattro livelli, il che significa che una stringa expand non può contenere più di quattro proprietà: property1..
Ampliare le proprietà negli elenchi
Quando l’API restituisce un elenco di oggetti, puoi utilizzare la parola chiave data per ampliare una determinata proprietà per ogni oggetto di tale elenco. Ad esempio, supponiamo che tu abbia bisogno di informazioni sulle modalità di pagamento utilizzate da uno dei tuoi clienti. Per ottenerle, devi creare un elenco dei PaymentIntent del cliente, che restituisce un oggetto con la seguente struttura:
{ "object": "list", "data": [ { "id": "pi_1GrvBKLHughnNhxy6N28q8gt", "object": "payment_intent", "amount": 1000, ... "payment_method": "pm_1GrvBxLHughnNhxyJjtBtHcc", ... },
Nota
Tutti gli elenchi restituiti nell’API hanno la struttura sopra indicata, dove la proprietà data contiene la matrice degli oggetti elencati. Puoi utilizzare la parola chiave data in qualsiasi posizione di una stringa Expand per spostare il cursore di ampliamento all’interno dell’elenco.
Anziché riprodurre a ciclo continuo ogni Payment Intent dell’elenco e recuperare le modalità di pagamento collegate in chiamate distinte, puoi ampliare tutte le modalità di pagamento contemporaneamente utilizzando la parola chiave data:
L’elenco include quindi l’oggetto modalità di pagamento completo in ciascun Payment Intent:
{ "object": "list", "data": [ { "id": "pi_1GrvBKLHughnNhxy6N28q8gt", "object": "payment_intent", "amount": 1000, ... "payment_method": { "id": "pm_1GrvBxLHughnNhxyJjtBtHcc", "object": "payment_method", "billing_details": {...}, "card": { "brand": "visa", ...
Nota
L’ampliamento delle risposte ha un impatto sulle prestazioni. Per preservare la velocità delle risposte, prova a limitare il numero di ampliamenti nidificati nelle richieste di elenchi.
Utilizzo dell’espansione per richiedere le proprietà che possono essere incluse
In alcuni casi le risorse hanno proprietà che non sono incluse per impostazione predefinita. La proprietà line_items della sessione Checkout rappresenta un buon esempio: essa viene inclusa nelle risposte solo se richiesta mediante il parametro expand. Ad esempio:
Nota
Come le altre proprietà ampliabili, la documentazione di riferimento dell’API contrassegna le proprietà che possono essere incluse con l’etichetta “Ampliabile”.
Utilizzo dell’espansione con i webhook
Non puoi ricevere eventi webhook con le proprietà ampliate automaticamente. Gli oggetti inviati negli eventi sono sempre presentati nella loro forma minima. Per accedere ai valori nidificati nelle proprietà ampliabili, devi recuperare l’oggetto con una chiamata distinta nel tuo gestore webhook.