Du kannst den oEmbed-Endpunkt von Instagram abfragen, um den HTML-Einbettungscode und grundlegende Metadaten eines Instagram-Beitrags zu erhalten und den Beitrag auf einer anderen Website oder in einer anderen App anzuzeigen. Das Posten von Fotos, Videos, Reels und Guides wird unterstützt.
Endpunkt | Beschreibung |
---|---|
Den HTML-Einbettungscode und grundlegende Metadaten eines Instagram-Beitrags abrufen |
Um oEmbed nutzen zu können, muss deine App einer App-Review für das Feature oEmbed Read unterzogen werden.
Verwende für das Formularfeld zum Bereitstellen einer URL, unter der wir oEmbed Read testen können, den Instagram oEmbed-Endpunkt, um den HTML-Einbettungscode für alle öffentlichen Beiträge auf unserer offiziellen Facebook-Seite oder Instagram-Seite abzurufen (oder rufe den HTML-Einbettungscode für eine der Seiten selbst ab). Füge den zurückgegebenen HTML-Einbettungscode deiner eigenen Seite hinzu, auf der du oEmbed-Inhalt anzeigen möchtest und gib die URL dieser Seite in das Formularfeld ein.
Sobald du eine Genehmigung für das Feature oEmbed Read erhalten hast, kannst du deine eigenen Seiten, Posts oder Videos einbetten, indem du die entsprechenden URLs verwendest.
Für den oEmbed-Endpunkt von Instagram wird entweder ein App-Zugriffsschlüssel (empfohlen) oder ein Client-Zugriffsschlüssel benötigt.
Wenn deine App einen Backend-Server verwendet, empfehlen wir, beim Zugriff auf den oEmbed-Endpunkt einen App-Zugriffsschlüssel zu verwenden. Ratenbegrenzungen hängen von der Art des Zugriffsschlüssels ab, der in der Anfrage enthalten ist, und Ratenbegrenzungen für App-Zugriffsschlüssel erlauben bis zu 5 Millionen Anfragen pro Tag.
Eine Anleitung zur Generierung von App-Zugriffsschlüsseln findest du in unserer Dokumentation „Zugriffsschlüssel“ im Abschnitt „App-Zugriffsschlüssel“.
Beachte bitte, dass App-Zugriffsschlüssel niemals clientseitig verwendet werden sollen. Sie sollten immer sicher aufbewahrt und auf deinem Server gespeichert werden. Wenn deine App einen Zugriffsschlüssel clientseitig verwenden muss, verwende stattdessen einen Client-Zugriffsschlüssel.
Wenn deine App über einen Nutzeragenten wie ein Mobilgerät oder einen Webbrowser auf den oEmbed-Endpunkt zugreifen muss, muss deine App einen Client-Zugriffsschlüssel verwenden und unterliegt Ratenbegrenzungen für Client-Zugriffsschlüssel.
Um einen Client-Zugriffsschlüssel zu erhalten, melde dich bei deinem App-Dashboard an und navigiere zu Einstellungen > Erweitert > Sicherheit > Client Token.
Im Gegensatz zu App-Zugriffsschlüsseln können Client-Zugriffsschlüssel nicht allein in oEmbed-Endpunktanfragen verwendet werden. Sie müssen mit deiner App-ID kombiniert werden. Hänge dazu deinen Zugriffsschlüssel an das Ende deiner App-ID an, getrennt durch einen Senkrechtstrich (|
):
{app-id}|{client-token}
Zum Beispiel:
access_token=1234|5678
Ratenbegrenzungen hängen von der Art des Zugriffsschlüssels ab, den deine App in der jeweiligen Anfrage enthält.
Apps, die App-Zugriffsschlüssel verwenden, können innerhalb von 24 Stunden bis zu 5 Millionen Anfragen durchführen.
Ratenbegrenzungen für Client-Zugriffsschlüssel sind erheblich niedriger als Ratenbegrenzungen für App-Zugriffschlüssel. Wir geben die tatsächliche Grenze nicht an, da sie sich je nach deinen App-Aktivitäten ändert. Du kannst jedoch davon ausgehen, dass deine App die Grenze nur dann erreicht, wenn sie sich wie ein Bot verhält und etwa Tausende von Anfragen im Batch sendet oder Tausende von Anfragen pro Agent oder App-Nutzer sendet.
Um den HTML-Einbettungscode eines Instagram-Beitrags abzurufen, sende eine Anfrage an:
GET /instagram_oembed?url={url}&access_token={access-token}
Ersetze {url}
durch die URL des Instagram-Beitrags, den du abfragen möchtest, und {access-token}
durch deinen App- oder Client-Zugriffsschlüssel (oder übergib ihn in einem HTTP-Header an uns). Wenn du einen Client-Zugriffsschlüssel verwendest, denke daran, ihn unter Verwendung eines Senkrechtstrichs mit deiner App-ID zu kombinieren. Ansonsten schlägt die Anfrage fehl.
Ist die Anfrage erfolgreich, antwortet die API mit einem JSON-Objekt, das den HTML-Einbettungscode des Beitrags und zusätzliche Daten enthält. Der HTML-Einbettungscode wird der Eigenschaft html
zugewiesen.
In der Referenz zu oEmbed von Instagram findest du eine Liste der Abfrage-String-Parameter, die du einschließen kannst, um die Abfrage zu erweitern. Du kannst auch den Abfrage-String-Parameter fields
einschließen, um anzugeben, welche Felder zurückgegeben werden sollen. Wird keine Angabe gemacht, sind in der Antwort alle Standardfelder enthalten.
curl -X GET \
"https://graph.facebook.com/v20.0
/instagram_oembed?url=https://www.instagram.com/p/fA9uwTtkSN/&access_token=IGQVJ..."
Einige Werte sind zur besseren Lesbarkeit mit Auslassungszeichen (...
) abgeschnitten.
{ "version": "1.0", "author_name": "diegoquinteiro", "provider_name": "Instagram", "provider_url": "https://www.instagram.com/", "type": "rich", "width": 658, "html": "<blockquote class=\"instagram-media\" data-instgrm-ca...", "thumbnail_width": 640, "thumbnail_height": 640 }
Der Abfrage-String-Parameter url
akzeptiert die folgenden URL-Formate:
https://www.instagram.com/p/{media-shortcode}/
https://www.instagram.com/tv/{media-shortcode}/
https://www.instagram.com/{username}/guide/{slug}/{guide_id}
Der HTML-Einbettungscode enthält eine Referenz zur JavaScript-Bibliothek embed.js von Instagram. Wenn die Bibliothek geladen wird, scannt sie die Seite nach dem Beitrags-HTML-Code und generiert den vollständig gerenderten Beitrag. Wenn du die Bibliothek separat laden möchtest, schließe den Abfrage-String-Parameter omitscript=true
in deine Abfrage ein. Um den HTML-Einbettungscode manuell zu initialisieren, rufe die Funktion instgrm.Embeds.process()
auf, nachdem die Bibliothek geladen wurde.
Der eingebettete Beitrag ist responsiv und wird an die Größe des Containers angepasst. Das bedeutet, dass die Höhe je nach Containerbreite und Länge der Bildunterschrift variiert. Du kannst die maximale Breite festlegen, indem du den Abfrage-String-Parameter maxwidth
in deine Abfrage einschließt.
Wir empfehlen dir, nach Möglichkeit den gesamten HTML-Einbettungscode des Beitrags zu rendern. Wenn dir das nicht möglich ist, kannst du die URL des Miniaturbilds eines Beitrags abrufen und stattdessen dieses rendern. Wenn du das tust, musst du aber neben dem Bild eine klare Attribution angeben. Dazu zählen eine Attribution des ursprünglichen Autors und von Instagram sowie ein Link zum Instagram-Beitrag, den du abfragst.
Um die URL des Miniaturbilds und die Attributionsinformationen eines Beitrags abzurufen, sende eine Anfrage an:
GET /instagram_oembed ?url={url} &maxwidth={maxwidth} &fields=thumbnail_url,author_name,provider_name,provider_url &access_token={access-token}
Ersetze {url}
durch die URL des Instagram-Beitrags, den du abfragen möchtest, {maxwidth}
durch die maximale Größe des Miniaturbilds, das du rendern möchtest, und {access-token}
durch deinen App- oder Client-Zugriffsschlüssel.
curl -i -X GET \
"https://graph.facebook.com/v20.0
/instagram_oembed?url=https%3A%2F%2Fwww.instagram.com%2Fp%2FfA9uwTtkSN&maxwidth=320&fields=thumbnail_url%2Cauthor_name%2Cprovider_name%2Cprovider_url&access_token=96481..."
Einige Werte sind zur besseren Lesbarkeit mit Auslassungszeichen (...
) abgeschnitten.
{ "thumbnail_url": "https://scontent.cdninstagram.com/v/t51.288...", "author_name": "diegoquinteiro", "provider_name": "Instagram", "provider_url": "https://www.instagram.com/" }
Wenn du deinen Zugriffsschlüssel nicht in den Abfrage-String deiner Anfrage einschließen möchtest, kannst du ihn stattdessen über einen Authorization
-HTTP-Header an uns übergeben.
Authorization: Bearer {access-token}
Zum Beispiel:
curl -i -X GET \
"https://graph.facebook.com/v20.0
/instagram_oembed?url=https%3A%2F%2Fwww.instagram.com%2Fp%2FfA9uwTtkSN" \
--header "Authorization: Bearer 96481..."