Graph API

Plattform-Versionierung

Die Facebook-Plattform unterstützt die Versionierung. App-Entwickler können somit im Laufe der Zeit Änderungen vornehmen. In diesem Dokument erläutern wir, welche Auswirkungen Versionen auf SDKs und APIs haben und wie du diese Versionen in deinen Anfragen verwendest.

Versionierung

Nicht alle APIs und SDKs nutzen dasselbe Versionierungssystem. So wird beispielsweise die Graph API in einem anderen Tempo und mit einer anderen Nummerierung versioniert als das Facebook-SDK für iOS. Alle Facebook-SDKs unterstützen die Interaktion mit verschiedenen Versionen unserer APIs. Es können mehrere API- oder SDK-Versionen zeitgleich vorhanden sein, wobei die einzelnen Versionen unterschiedliche Funktionen aufweisen können.

Welche ist die aktuellste Graph API-Version?

Die neueste Graph API-Version ist v21.0

Warum gibt es Versionen?

Das Ziel bei der Versionierung ist, dass Entwickler von Apps im Voraus wissen, wann Änderungen an einer API oder an einem SDK vorgenommen werden. Versionen sind bei der Web-Entwicklung hilfreich, aber bei der Entwicklung für Mobilgeräte sehr wichtig, weil es recht lange dauern kann, bis Personen, die deine App auf ihrem Smartphone nutzen, ein Upgrade durchführen (wenn sie es überhaupt tun).

Jede Version bleibt nach ihrer Veröffentlichung für mindestens 2 Jahre verfügbar. Durch diese feste Zeitvorgabe weißt du immer, wie lange deine App funktionsfähig bleibt und wann ein Update auf neuere Versionen erforderlich ist.

Versionszeitpläne

Jede Version hat eine garantierte Funktionszeit von mindestens zwei Jahren. Zwei Jahre nach der Veröffentlichung der Nachfolgeversion kann eine Version nicht mehr genutzt werden. Wenn die API-Version v2.3 beispielsweise am 25. März 2015 und die API-Version v2.4 am 7. August 2015 veröffentlicht wurde, dann ist v2.3 am 7. August 2017, also zwei Jahre nach der Veröffentlichung von v2.4, abgelaufen.

Ist eine API-Version abgelaufen, werden standardmäßig alle Anrufe an diese Version an die nächstältere, verfügbare Version weitergeleitet. Hier ist ein Beispiel mit einer Zeitachse:

Bei SDKs bleiben die Versionen immer verfügbar, da es sich um herunterladbare Pakete handelt. Das SDK bezieht sich jedoch möglicherweise auf APIs oder Methoden, die abgelaufen sind. Du solltest also davon ausgehen, dass ein SDK nach Ablauf der Lebensdauer nicht mehr funktioniert.

Konkrete Informationen zu unseren Versionszeitachsen sowie zu Änderungen und Veröffentlichungsdaten findest du auf unserer Änderungsprotokollseite.

Wird in einer Version gar nichts verändert?

Facebook behält sich das Recht vor, bei sicherheits- oder datenschutzrelevanten Problemen kurzfristig Änderungen vorzunehmen. Derartige Änderungen kommen nicht oft vor, aber sie kommen vor.

Was passiert, wenn ich keine API-Version angebe?

API-Anrufe, die ohne Angabe einer Version getätigt werden, bezeichnen wir als nichtversionierten Anruf. Angenommen, die aktuelle Version ist beispielsweise Version 4.0. Der Aufruf lautet wie folgt:

curl -i -X "https://graph.facebook.com/v4.0/{my-user-id}&access_token={access-token}"

Der gleiche Aufruf ohne Versionsangabe lautet wie folgt:

curl -i -X "https://graph.facebook.com/{my-user-id}&access_token={access-token}"

Ein nichtversionierter Anruf verwendet die auf der App-Dashboard-Karte Upgrade für API Version unter Einstellungen > Erweitert festgelegte Version. Im folgenden Beispiel ist im App-Dashboard Version v2.10 festgelegt und der Aufruf ohne Versionsangabe lautet wie folgt:

curl -i -X "https://graph.facebook.com/v2.10/{my-user-id}&access_token={access-token}"

Wir empfehlen, nach Möglichkeit immer die Version anzugeben.

Einschränkungen

  • Nichtversionierte Aufrufe für das Facebook JavaScript-SDK werden nicht unterstützt.

Kann meine App Aufrufe an Versionen tätigen, die älter als die aktuelle Version sind?

Du kannst ältere Versionen in deinen API-Aufrufen angeben, solange sie verfügbar sind und deine App Aufrufe an diese Versionen ausgeführt hat. Wenn deine App beispielsweise nach der Veröffentlichung von v2.0 erstellt wurde und Aufrufe unter Verwendung von v2.0 ausführt, können diese bis zum Ablauf von v2.0 weiterhin ausgeführt werden, selbst wenn bereits neuere Versionen veröffentlicht wurden. Wenn du deine App nach v2.0 erstellt hast, aber bis v2.2 keine Aufrufe vorgenommen hast, kann deine App keine Aufrufe an v2.0 oder v2.1 ausführen. In dem Fall sind nur Aufrufe unter Verwendung von v2.2 und neueren Versionen möglich.

Marketing API – Versionierung

Die Marketing API verfügt über ein eigenes Versionierungsschema. Die beiden Versionsnummern und ihre Zeitpläne unterscheiden sich von den Gegebenheiten bei der Graph API.

Erfahre hier mehr über die Versionierung der Marketing API

Stellen von versionierten Anfragen

Graph API

Für Core oder Erweitert sind fast alle Graph API-Endpunkte über einen versionierten Pfad verfügbar. Du findest einen vollständigen Leitfaden für die Verwendung von Versionen mit der Graph API in unserer Graph API-Kurzanleitung.

Dialoge

Versionierte Pfade gelten nicht nur für API-Endpunkte sondern auch für Dialoge und soziale Plugins. Wenn du beispielsweise den Facebook Login-Dialog für eine Web-App generieren möchtest, kannst du dem Endpunkt, der den Dialog generiert, eine Versionsnummer voranstellen:

https://www.facebook.com/v21.0/dialog/oauth?
  client_id={app-id}
  &redirect_uri={redirect-uri}

Soziale Plugins

Wenn du die HTML5- oder xfbml-Versionen unserer sozialen Plugins verwendest, wird die gerenderte Version durch die Version bestimmt, die du bei der Initialisierung des JavaScript-SDKs angegeben hast.

Wenn du ein iframe- oder eine einfache Link-Version eines unserer Plugins einfügst, stellst du dem Quellpfad des Plugins die Versionsnummer voran:

<iframe
  src="//www.facebook.com/v21.0/plugins/like.php?href=https%3A%2F%2Fdevelopers.facebook.com%2Fdocs%2Fplugins%2F&amp;width&amp;layout=standard&amp;action=like&amp;show_faces=true&amp;share=true&amp;height=80&amp;appId=634262946633418" 
  scrolling="no" 
  frameborder="0" 
  style="border:none; overflow:hidden; height:80px;" 
  allowTransparency="true">
</iframe>

Versionierte Anrufe von SDKs tätigen

Wenn du das Facebook-SDK für iOS, Android oder JavaScript verwendest, werden Versionierungsaufrufe größtenteils automatisch ausgeführt. Bitte beachte, dass sich dieses System von den eigenen Versionierungssystemen der verschiedenen SDKs unterscheidet.

JavaScript

Das JavaScript-SDK unterstützt nur dann verschiedene API-Versionen, wenn du den Pfad sdk.js verwendest.

Wenn du FB.init() aus dem JavaScript-SDK verwendest, muss du den Versionsparameter wie folgt angeben:

FB.init({
  appId      : '{app-id}',
  version    : 'v21.0'
});

Wenn du das Versions-Flag in die init-Anweisung einfügst, weisen alle Anrufe am FB.api() automatisch die Version auf, die dem angerufenen Pfad vorangestellt wurde. Das Gleiche gilt für alle Facebook Login-Dialoge, die aufgerufen werden. Es wird der Facebook Login-Dialog für diese Version der API angezeigt.

Du kannst gegebenenfalls eine Version überschreiben, indem du einfach die Version dem Pfad des Endpunkts im FB.api() voranstellst.

iOS

Alle veröffentlichten Versionen des Facebook-SDKs für iOS sind mit der Version verknüpft, die am Tag der Veröffentlichung verfügbar war. Wenn du ein Upgrade auf ein neues SDK durchführst, wird gleichzeitig auch ein Upgrade auf die neueste API-Version vorgenommen (du kannst aber manuell mit [FBSDKGraphRequest initWithGraphPath] jede ältere API-Version angeben, die noch verfügbar ist). Die API-Version wird mit der Veröffentlichung jeder Version des Facebook-SDKs für iOS angegeben.

Ähnlich wie beim JavaScript-SDK wird die Version allen Aufrufen vorangestellt, die du über das Facebook-SDK für iOS an die Graph-API ausführst. Beispiel: Wenn v2.7 die aktuellste API-Version war, wird mit dem im folgenden Codebeispiel verwendeten Aufruf /me/friends tatsächlich /v2.7/me/friends aufgerufen:

[[[FBSDKGraphRequest alloc] initWithGraphPath:@"me/friends"
  parameters:@{@"fields": @"cover,name,start_time"}]
    startWithCompletionHandler:^(FBSDKGraphRequestConnection *connection, id result, NSError *error) {
        (...)
    }];

Die kannst die Version des Anrufs mit [FBSDKGraphRequestConnection overrideVersionPartWith] überschreiben.

Android

Alle veröffentlichten Versionen des Facebook-SDKs für Android sind mit der Version verknüpft, die am Tag der Veröffentlichung verfügbar war. Wenn du ein Upgrade auf ein neues SDK durchführst, wird gleichzeitig auch ein Upgrade auf die neueste API-Version vorgenommen (du kannst aber manuell mit GraphRequest.setVersion() jede ältere API-Version angeben, die noch verfügbar ist). Die API-Version wird mit der Veröffentlichung jeder Version des Facebook-SDKs für Android angegeben.

Ähnlich wie beim JavaScript-SDK wird die Version allen Aufrufen vorangestellt, die du über das Facebook-SDK für Android an die Graph-API ausführst. Beispiel: Wenn v2.7 die aktuellste API-Version war, wird mit dem im folgenden Codebeispiel verwendeten Aufruf /me tatsächlich /v2.7/me aufgerufen:

GraphRequest request = GraphRequest.newGraphPathRequest (
        accessToken,
        "/me/friends",
        new GraphRequest.GraphJSONObjectCallback() {
            @Override
            public void onCompleted(
                   JSONObject object,
                   GraphResponse response) {
                // Application code
            }
        });
Bundle parameters = new Bundle();
parameters.putString("fields", "id,name,link");
request.setParameters(parameters); 
request.executeAsync();

Du kannst die Version des Anrufs mit GraphRequest.setVersion() überschreiben.