# Erweiterung der Antworten Erfahren Sie, wie Sie die Anzahl der Anfragen an die Stripe-API reduzieren können, indem Sie Objekte in Antworten erweitern. In diesem Leitfaden wird beschrieben, wie Sie zusätzliche Eigenschaften von der API anfordern können. Sie erfahren, wie Sie Ihre Anfragen so ändern, dass sie Folgendes enthalten: - Eigenschaften von verwandten Objekten - Eigenschaften von entfernt verwandten Objekten - Zusätzliche Eigenschaften auf alle Objekte in einer Liste - Eigenschaften, die nicht standardmäßig in einer Antwort enthalten sind ## Funktionsweise Die Stripe-API ist in Ressourcen organisiert, die durch Objekte mit Status-, Konfigurations- und Kontexteigenschaften dargestellt werden. Diese Objekte haben alle eindeutige IDs, mit denen Sie sie abrufen, aktualisieren und löschen können. Die API verwendet diese IDs auch, um verwandte Objekte miteinander zu verknüpfen. Eine [Checkout-Sitzung](https://docs.stripe.com/api/checkout/sessions/object.md) ist beispielsweise über die [Kunden-ID](https://docs.stripe.com/api/checkout/sessions/object.md#checkout_session_object-customer) mit einem [Kunden](https://docs.stripe.com/api/customers/object.md) verbunden. ```json { "id": "cs_test_KdjLtDPfAjT1gq374DMZ3rHmZ9OoSlGRhyz8yTypH76KpN4JXkQpD2G0", "object": "checkout.session", ..."customer": "cus_HQmikpKnGHkNwW", ... } ``` In Fällen, in denen Sie Informationen von einem verknüpften Objekt benötigen, können Sie das verknüpfte Objekt in einem neuen Aufruf über seine ID abrufen. Dieser Ansatz erfordert jedoch zwei API-Anforderungen für den Zugriff auf nur einen Wert. Wenn Sie Informationen von mehreren verknüpften Objekten benötigen, würde jede einzelne Anforderung ebenfalls separate Anforderungen erfordern, was die Latenzzeit und Komplexität Ihrer Anwendung erhöht. Die API verfügt über eine Erweiterungsfunktion, mit der Sie verknüpfte Objekte in einem einzigen Aufruf abrufen können, wobei die Objekt-ID effektiv durch alle Eigenschaften und Werte ersetzt wird. Angenommen, Sie möchten auf Details zu einem Kunden/einer Kundin zugreifen, der an eine bestimmte Checkout-Sitzung gebunden ist. Sie würden die Checkout-Sitzung abrufen und die Eigenschaft `customer` an das Array `expand` übergeben, das Stripe anweist, das gesamte Kundenobjekt in die Antwort aufzunehmen: ```curl curl -G https://api.stripe.com/v1/checkout/sessions/{{CHECKOUTSESSION_ID}} \ -u "<>:" \ -d "expand[]=customer" ``` Dies gibt die Checkout-Sitzung mit dem vollständigen Kundenobjekt anstelle seiner ID zurück: ```json { "id": "cs_test_KdjLtDPfAjT1gq374DMZ3rHmZ9OoSlGRhyz8yTypH76KpN4JXkQpD2G0", "object": "checkout.session", ..."customer": { "id": "cus_HQmikpKnGHkNwW", "object": "customer", ... "metadata": { "user_id": "user_xyz" }, ... } } ``` > Nicht alle Eigenschaften können erweitert werden. Die API-Referenz kennzeichnet erweiterbare Eigenschaften mit der Beschriftung „Erweiterbar“. ## Erweiterung mehrerer Eigenschaften Um mehrere Eigenschaften in einem Aufruf zu erweitern, fügen Sie zusätzliche Elemente zum Array Expand hinzu. Wenn Sie zum Beispiel sowohl [customer](https://docs.stripe.com/api/checkout/sessions/object.md#checkout_session_object-customer) als auch [payment_intent](https://docs.stripe.com/api/checkout/sessions/object.md#checkout_session_object-payment_intent) für eine bestimmte Checkout-Sitzung erweitern möchten, würden Sie `expand` ein Array mit den Zeichenfolgen `customer` und `payment_intent` übergeben: ```curl curl -G https://api.stripe.com/v1/checkout/sessions/{{CHECKOUTSESSION_ID}} \ -u "<>:" \ -d "expand[]=customer" \ -d "expand[]=payment_intent" ``` ## Erweiterung mehrerer Ebenen Wenn der gewünschte Wert tief über mehrere verknüpfte Ressourcen verschachtelt ist, können Sie ihn durch rekursives Erweitern in Punktschreibweise erreichen. Wenn Sie z. B. den Typ der Zahlungsmethode wissen möchten, die für eine bestimmte Checkout-Sitzung verwendet wurde, würden Sie zuerst die Zahlungsabsicht der Checkout-Sitzung abrufen und dann die mit der Zahlungsabsicht verknüpfte Zahlungsmethode, um deren Typ zu erhalten. Mit `expand` können Sie dies in einem einzigen Aufruf erledigen: ```curl curl -G https://api.stripe.com/v1/checkout/sessions/{{CHECKOUTSESSION_ID}} \ -u "<>:" \ -d "expand[]=payment_intent.payment_method" ``` Dies gibt die Checkout-Sitzung mit den vollständigen Objekten [PaymentIntent](https://docs.stripe.com/api/payment_intents/object.md) und [PaymentMethod](https://docs.stripe.com/api/payment_methods/object.md) anstelle ihrer IDs zurück: ```json { "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": {...}, "created": 1589902798, "customer": "cus_HQmikpKnGHkNwW", "livemode": false, "metadata": {}, "type": "card" }, "payment_method_options": {...}, "payment_method_types": [ "card" ], "receipt_email": "jenny.rosen@gmail.com", "review": null, "setup_future_usage": null, "shipping": null, "source": null, "statement_descriptor": null, "statement_descriptor_suffix": null, "status": "succeeded", "transfer_data": null, "transfer_group": null }, "payment_method_types": [ "card" ], "setup_intent": null, "shipping": null, "shipping_address_collection": null, "submit_type": null, "subscription": null, "success_url": "http://localhost:5000" } ``` > Erweiterungen haben eine maximale Tiefe von vier Ebenen. Das bedeutet, dass eine `expand`-Zeichenfolge nicht mehr als vier Eigenschaften enthalten kann: `property1.property2.property3.property4`. ## Erweiterung von Eigenschaften in Listen Wenn die API eine Liste von Objekten zurückgibt, können Sie das Schlüsselwort `data` verwenden, um eine bestimmte Eigenschaft für jedes Objekt in dieser Liste zu erweitern. Angenommen, Sie benötigen Informationen über die von einem Ihrer Kunden/einer Ihrer Kundinnen verwendeten Zahlungsmethoden. Um diese Informationen zu erhalten, würden Sie die [PaymentIntents des Kunden/der Kundin auflisten](https://docs.stripe.com/api/payment_intents/list.md#list_payment_intents-customer), was ein Objekt mit der folgenden Struktur zurückgibt: ```json { "object": "list","data": [ { "id": "pi_1GrvBKLHughnNhxy6N28q8gt", "object": "payment_intent", "amount": 1000, ..."payment_method": "pm_1GrvBxLHughnNhxyJjtBtHcc", ... }, { "id": "pi_1Grv8tLHughnNhxyflPG4bMG", "object": "payment_intent", "amount": 4000, ..."payment_method": "pm_1Grv9zLHughnNhxyv6uMNomv", ... } ], "has_more": false, "url": "/v1/payment_intents" } ``` > Alle in der API zurückgegebenen Listen haben die obige Struktur, wobei die Eigenschaft `data` das Array der aufgelisteten Objekte enthält. Sie können das Schlüsselwort `data` an einer beliebigen Position in einer Erweiterungszeichenfolge verwenden, um den Erweiterungscursor in die Liste zu bewegen. Anstatt in einer Schleife durch jede Zahlungsabsicht in der Liste zu gehen und die verknüpften Zahlungsmethoden in separaten Aufrufen abzurufen, können Sie mit dem Schlüsselwort `data` alle Zahlungsmethoden auf einmal erweitern: ```curl curl -G https://api.stripe.com/v1/payment_intents \ -u "<>:" \ -d "customer={{CUSTOMER_ID}}" \ -d "expand[]=data.payment_method" ``` Die Liste enthält dann das vollständige Zahlungsmethodenobjekt zu jedem Payment Intent: ```json { "object": "list", "data": [ { "id": "pi_1GrvBKLHughnNhxy6N28q8gt", "object": "payment_intent", "amount": 1000, ..."payment_method": { "id": "pm_1GrvBxLHughnNhxyJjtBtHcc", "object": "payment_method", "billing_details": {...}, "card": { "brand": "visa", ... "country": "US", "exp_month": 2, "exp_year": 2022, "fingerprint": "1212u2LvSFqEHu3h", "funding": "credit", "last4": "4242", ... }, "created": 1591661989, "customer": "cus_HQmikpKnGHkNwW", "livemode": false, "metadata": {...}, "type": "card" }, ... }, { "id": "pi_1Grv8tLHughnNhxyflPG4bMG", "object": "payment_intent", "amount": 4000, ..."payment_method": { "id": "pm_1Grv9zLHughnNhxyv6uMNomv", "object": "payment_method", "billing_details": {...}, "card": { "brand": "visa", "checks": {...}, "country": "US", "exp_month": 2, "exp_year": 2025, "fingerprint": "1212u2LvSFqEHu3h", "funding": "credit", "generated_from": null, "last4": "0341", "three_d_secure_usage": {...}, "wallet": null }, "created": 1591661989, "customer": "cus_HQmikpKnGHkNwW", "livemode": false, "metadata": {...}, "type": "card" }, ... } ], "has_more": false, "url": "/v1/payment_intents" } ``` > Das Erweitern von Antworten hat Auswirkungen auf die Leistung. Um Anfragen schnell zu gestalten, versuchen Sie, viele verschachtelte Erweiterungen bei Listenanfragen zu vermeiden. ## Verwendung der Expansion, um einbeziehbare Eigenschaften anzufordern In einigen Fällen haben Ressourcen Eigenschaften, die standardmäßig nicht enthalten sind. Ein Beispiel ist die Eigenschaft [line_items](https://docs.stripe.com/api/checkout/sessions/object.md#checkout_session_object-line_items) der Checkout-Sitzung, die nur in Antworten enthalten ist, wenn sie z. B. mit dem Parameter `expand` angefordert wird: ```curl curl -G https://api.stripe.com/v1/checkout/sessions/{{CHECKOUTSESSION_ID}} \ -u "<>:" \ -d "expand[]=line_items" ``` > Wie andere erweiterbare Eigenschaften markiert die API-Referenz einbeziehbare Eigenschaften mit der Bezeichnung „Erweiterbar“. ## Verwendung der Expansion mit Webhooks Sie können keine *Webhook* (A webhook is a real-time push notification sent to your application as a JSON payload through HTTPS requests)-Ereignisse mit automatisch erweiterten Eigenschaften empfangen. Objekte, die in Ereignissen gesendet werden, sind immer in ihrer Minimalform. Um auf verschachtelte Werte in erweiterbaren Eigenschaften zuzugreifen, müssen Sie das Objekt in einem separaten Aufruf innerhalb Ihres Webhook-Handlers abrufen.