Übersicht

Die Instagram Basic Display API ist eine HTTP-basierte API, mit der Apps Profile, Bilder, Videos und Alben in Instagram-Konten abrufen können.

Komponenten

Basis-URLs

• api.instagram.com: für den Abruf von Instagram-Nutzer-Zugriffsschlüsseln
• graph.instagram.com: für den Abruf von Instagram-Nutzer*innenprofilen und Medien

Versionen

Die API unterstützt dasselbe Versionierungsprotokoll und denselben Release-Zyklus wie die Facebook Graph API. Ungefähr alle drei Monate werden neuen Versionen veröffentlicht. Jede Version wird nach etwa zwei Jahren eingestellt.

Um eine bestimmte API-Version abzufragen, gib die Versionsnummer nach der Basis-URL im Abfragepfad an. Zum Beispiel:

https://graph.instagram.com/v11.0/10218560180051171/media

Wenn du die Versionsnummer in der Anfrage weglässt, nutzt die Anfrage die Version, die unter App-Dashboard > Einstellungen > Erweitert > API-Version aktualisieren angegeben ist.

Autorisierungsfenster

Mithilfe des Autorisierungsfensters kann deine App Autorisierungscodes und Berechtigungen von App-Nutzer*innen abrufen. Autorisierungscodes können gegen Instagram-Nutzer-Zugriffsschlüssel getauscht werden, die bei der Anforderung des Profils eines*einer App-Nutzer*in oder seiner Medien angegeben werden müssen.

Befolge zur Implementierung des Autorisierungsfensters unseren Leitfaden Abrufen von Zugriffsschlüsseln.

Autorisierungscodes

Autorisierungscodes können gegen kurzlebige Instagram-Nutzer-Zugriffsschlüssel getauscht werden. Implementiere das Autorisierungsfenster in deiner App, um einen Autorisierungscode zu erhalten. Sobald ein*e App-Nutzer*in seine*ihre Identität über das Fenster authentifiziert und deiner App alle notwendigen Berechtigungen gewährt hat, leiten wir den*die Nutzer*in zu deiner App weiter und schließen einen Autorisierungscode ein. Mithilfe der API kannst du dann den Code gegen den kurzlebigen Instagram-Nutzer-Zugriffsschlüssel des*der App-Nutzer*in tauschen.

Autorisierungscodes sind kurzlebig und nur eine Stunde lang gültig.

Instagram-Nutzer-Zugriffsschlüssel

Die API-Authentifizierung erfolgt über Instagram-Nutzer-Zugriffsschlüssel, die das OAuth 2.0-Protokoll erfüllen. Zugriffsschlüssel sind App-spezifisch (beziehen sich auf das App-Nutzer*innen-Paar) und können kurz- oder langlebig sein. API-Anfragen, die Instagram-Nutzer*innen oder deren Medien abfragen, müssen einen Instagram-Nutzer-Zugriffsschlüssel enthalten.

Kurzlebige Zugriffsschlüssel

Kurzlebige Zugriffsschlüssel sind eine Stunde lang gültig, können jedoch gegen langlebige Schlüssel ausgetauscht werden. Implementiere das Autorisierungsfenster in deiner App, um einen kurzlebigen Zugriffsschlüssel zu erhalten. Sobald ein*e App-Nutzer*in seine*ihre Identität über das Fenster authentifiziert hat, leiten wir den*die Nutzer*in wieder zu deiner App und schließen einen Autorisierungscode ein, den du dann gegen einen kurzlebigen Zugriffsschlüssel tauschen kannst.

Langlebige Zugriffsschlüssel

Kurzlebige Zugriffsschlüssel, die nicht abgelaufen sind, können gegen langlebige Schlüssel getauscht werden, die eine Gültigkeit von 60 Tagen haben. Langlebige Schlüssel können vor dem Ablauf aktualisiert werden. Sende hierzu eine Anfrage an den GET /refresh_access_token-Endpunkt.

Berechtigungen

Die Autorisierung des Datenzugriffs wird durch deine App-Nutzer*innen gesteuert, indem sie die unten aufgeführten Berechtigungen verwenden. Nutzer*innen müssen deiner App über das Autorisierungsfenster diese Berechtigungen gewähren, bevor deine App auf deren Daten zugreifen kann.

• instagram_graph_user_profile: Erlaubt deiner App, den Nutzer-Node, der den*die Instagram-Nutzer*in darstellt, und die Edges des Node zu lesen.
• instagram_graph_user_media: Erlaubt deiner App, den Medien-Node, der ein Bild, Video oder Album darstellt, und die Edges des Node zu lesen.

Instagram-Tester können deiner App diese Berechtigungen jederzeit erteilen. Damit App-Nutzer*innen ohne Rolle in deiner App diese Berechtigungen erteilen können, muss jede Berechtigung erst über den App-Review-Prozess für erweiterten Zugriff genehmigt werden. Außerdem muss sich deine App im Live-Modus befinden.

Berechtigungserteilungen von App-Nutzer*innen mit öffentlichen Konten sind 90 Tage gültig. Das Aktualisieren des langlebigen Zugriffsschlüssels eines*einer App-Nutzer*in verlängert die Berechtigungserteilung um weitere 90 Tage. Dies setzt voraus, dass der*die App-Nutzer*in, der*die den Schlüssel erteilt hat, ein öffentliches Konto besitzt. Sollte jedoch das Konto des*der App-Nutzer*in privat sein, kann die Berechtigungserteilung nicht verlängert werden und der*die App-Nutzer*in muss deiner App wieder die abgelaufene Berechtigung erteilen.

Instagram-Tester

Um deine App bei einem*einer Instagram-Nutzer*in testen zu können, musst du zuerst eine Einladung an das Konto des*der Instagram-Nutzer*in senden und warten, bis dieser die Einladung annimmt. Einladungen können im Abschnitt Instagram Tester auf der Registerkarte App-Dashboard > Rollen > Rollen gesendet werden.

Instagram-Nutzer*innen können Einladungen unter (Profilsymbol) > Profil bearbeiten > Apps und Websites > Tester-Einladungen auf der Instagram-Website oder in der mobile App nach der Anmeldung am Konto annehmen.

Ressourcen

Daten in der API bestehen aus Instagram-Nutzer*innen und deren Medien (Bilder, Videos und Alben). Alle Daten sind durch Berechtigungen geschützt. Damit deine App auf die Daten eines*einer Nutzer*in zugreifen kann, muss der*die Nutzer*in deiner App über das Autorisierungsfenster die entsprechende Berechtigung gewähren.

Nutzer*innen

Instagram-Nutzer*innen und ihre Profile werden durch Nutzer-Nodes dargestellt. Beachte, dass ältere API-Nutzer-IDs von Instagram nicht mit der Instagram Basic Display API kompatibel sind.

Medien

Fotos, Videos und Alben werden durch Medien-Nodes dargestellt und zu einzelnen Nutzer*innen erstellt.

Durchsatzratenbegrenzungen

Alle Endpunktanfragen unterliegen der Plattform-Durchsatzratenbegrenzung der Graph API.

Die aktuell verbrauchte Anzahl von Aufrufen deiner App findest du unter App-Dashboard > Instagram > Durchsatzratenbegrenzung für Basic Display, nachdem du deiner App das Produkt Instagram hinzugefügt hast.

App-Typen

Apps, die als Business-Apps gekennzeichnet sind, werden nicht unterstützt. Ist deine App eine Business-App, verwende alternativ die Instagram Graph API oder erstelle eine neue App, die keine Business-App ist.

App-Review

Instagram-Tester können deiner App jederzeit Instagram-Berechtigungen erteilen. Damit App-Nutzer*innen ohne Rolle in deiner App Instagram-Berechtigungen erteilen können, muss jede Berechtigung erst über den App-Review-Prozess für erweiterten Zugriff genehmigt werden. Außerdem muss sich deine App im Live-Modus befinden.

Wenn du mit der App-Entwicklung fertig und bereit bist, deine App in den Live-Modus zu schalten, lies unsere Dokumente zu App-Review, Beispieleinreichungen und häufigen Ablehnungsgründen, um mehr über den App-Review-Vorgang zu erfahren. Wenn du mit dem Vorgang vertraut bist, kannst du über den Tab App-Dashboard > Produkte > Instagram > Basic Display eine Genehmigung für Instagram Basic Display API-Berechtigungen anfordern.

Wenn du eine App ausschließlich zur Erstellung von Zugriffsschlüsseln mit dem User Token Generator entwickelst, musst du die App nicht zum App Review einreichen. Der User Token Generator erfordert keine Berechtigungen und kann mit einer App im Entwicklungsmodus genutzt werden.

Unternehmensverifizierung

Solange sich deine App noch im Entwicklungsmodus befindet, kann sie nur auf Daten in Instagram-Testkonten zugreifen. Bevor du deine App in den Live-Modus schalten und auf Daten in Nicht-Testkonten zugreifen kannst, musst du zunächst die Unternehmensverifizierung durchführen.

So funktioniert’s

Rufe zum Verwenden der API zuerst das Autorisierungsfenster ab und zeige es App-Nutzer*innen an. App-Nutzer authentifizieren sich über das Fenster und autorisieren deine App für den Zugriff auf ihre Daten, indem sie deiner App bestimmte Berechtigungen gewähren. Nach der Authentifizierung leitet das Fenster Nutzer*innen wieder zu deiner App und schließt einen Autorisierungscode ein. Notiere den Code und tausche ihn gegen einen kurzlebigen Instagram-Nutzer-Zugriffsschlüssel. Sobald du einen kurzlebigen Schlüssel hast, kannst du damit Nutzer- und Medien-Endpunkte auf alle Daten hin abfragen, auf die Nutzer*innen deiner App Zugriff erlaubt haben, oder diesen gegen einen langlebigen Schlüssel tauschen.

Tools

User Token Generator

Der Instagram User Token Generator ist ein Tool, mit dem du schnell langlebige Instagram-Nutzer-Zugriffsschlüssel für deine öffentlichen Instagram-Konten erstellen kannst. Das ist nützlich, wenn du deine App testest und dabei nicht das Autorisierungsfenster implementieren möchtest oder wenn du Code eines Drittanbieterdiensts verwendest, der kopiert und eingefügt werden kann (um beispielsweise deine eigenen Instagram-Daten auf deiner eigenen Website anzuzeigen).

Das Tool löst das Autorisierungsfenster aus, in dem du dich mit einem öffentlichen Instagram-Konto anmelden kannst, das du als Tester-Konto festgelegt hast. Nach der Anmeldung generiert das Tool einen langlebigen Zugriffsschlüssel, den du kopieren und einfügen kannst. Beachte, dass Schlüssel nur für öffentliche Instagram-Konten generiert werden können.

Du kannst über App-Dashboard > Produkte > Instagram > Basic Display auf das Tool zur Schlüsselerstellung zugreifen.

Wenn du eine App ausschließlich zur Erstellung von Zugriffsschlüsseln mit dem User Token Generator entwickelst, musst du die App nicht zum App Review einreichen. Der User Token Generator erfordert keine Berechtigungen und kann mit einer App im Entwicklungsmodus genutzt werden.

Nächste Schritte

In unserem Leitfaden für erste Schritte erfährst du, wie du eine App einrichten und eine einfache API-Anfrage stellen kannst.