OAuth 2.0 für TV-Apps und Geräteanwendungen mit begrenzter Eingabe

In diesem Dokument wird erläutert, wie die OAuth 2.0-Autorisierung implementiert wird, um über Anwendungen auf Geräten wie Fernsehern, Spielekonsolen und Druckern auf die YouTube Data API zuzugreifen. Dieser Ablauf ist für Geräte gedacht, die entweder keinen Zugriff auf einen Browser oder eingeschränkte Eingabemöglichkeiten haben.

OAuth 2.0 ermöglicht Nutzern, bestimmte Daten für eine Anwendung freizugeben, während ihre Nutzernamen, Passwörter und andere Informationen privat bleiben. Beispielsweise könnte eine TV-App OAuth 2.0 verwenden, um die Berechtigung zur Auswahl einer in Google Drive gespeicherten Datei zu erhalten.

Da die Anwendungen, die diesen Ablauf verwenden, auf einzelne Geräte verteilt sind, wird davon ausgegangen, dass die Anwendungen keine Geheimnisse behalten dürfen. Sie können auf Google APIs zugreifen, während der Nutzer die App verwendet oder die App im Hintergrund ausgeführt wird.

Alternativen

Wenn Sie eine App für eine Plattform wie Android, iOS, macOS, Linux oder Windows (einschließlich der Universal Windows-Plattform) schreiben, die Zugriff auf den Browser und vollständige Eingabefunktionen hat, verwenden Sie den OAuth 2.0-Vorgang für mobile und Desktop-Anwendungen. Sie sollten diesen Ablauf auch dann verwenden, wenn Ihre Anwendung ein Befehlszeilentool ohne grafische Benutzeroberfläche ist.

Wenn du Nutzer nur mit ihren Google-Konten anmelden und ein JWT-ID-Token verwenden möchtest, um grundlegende Nutzerprofilinformationen abzurufen, lies die Informationen unter Anmeldung auf Fernsehern und eingeschränkten Eingabegeräten.

Voraussetzungen

Die APIs für Ihr Projekt aktivieren

Jede Anwendung, die Google APIs aufruft, muss diese APIs im API Consoleaktivieren.

So aktivieren Sie eine API für Ihr Projekt:

  1. Open the API Library in der Google API Console.
  2. If prompted, select a project, or create a new one.
  3. Auf der Seite „Bibliothek“ kannst du die YouTube Data API suchen und aktivieren. Suchen Sie nach anderen APIs, die Ihre Anwendung verwenden wird, und aktivieren Sie diese ebenfalls.

Anmeldedaten für die Autorisierung erstellen

Anwendungen, die OAuth 2.0 für den Zugriff auf Google APIs verwenden, müssen Anmeldedaten zur Identifizierung gegenüber dem OAuth 2.0-Server von Google haben. In den folgenden Schritten wird erläutert, wie Sie Anmeldedaten für Ihr Projekt erstellen. Ihre Anwendungen können dann mit den Anmeldedaten auf APIs zugreifen, die Sie für das Projekt aktiviert haben.

  1. Go to the Credentials page.
  2. Klicken Sie auf Anmeldedaten erstellen > OAuth-Client-ID.
  3. Wählen Sie als Anwendungstyp Fernseher und eingeschränkte Eingabegeräte aus.
  4. Benennen Sie Ihren OAuth 2.0-Client und klicken Sie auf Erstellen.

Zugriffsbereiche identifizieren

Mithilfe von Bereichen kann Ihre Anwendung nur Zugriff auf die Ressourcen anfordern, die sie benötigt. Gleichzeitig können Nutzer den Umfang des Zugriffs steuern, den sie Ihrer Anwendung gewähren. Daher kann es eine umgekehrte Beziehung zwischen der Anzahl der angeforderten Bereiche und der Wahrscheinlichkeit des Einholens der Nutzereinwilligung geben.

Bevor Sie mit der Implementierung der OAuth 2.0-Autorisierung beginnen, sollten Sie die Bereiche identifizieren, für die Ihre App eine Zugriffsberechtigung benötigt.

Die YouTube Data API Version 3 nutzt die folgenden Bereiche:

Sucher
https://www.googleapis.com/auth/youtubeYouTube-Konto verwalten
https://www.googleapis.com/auth/youtube.channel-memberships.creatorEine Liste der aktuell aktiven Mitglieder des Kanals, ihre Stufe und ihr Eintrittsdatum abrufen
https://www.googleapis.com/auth/youtube.force-sslIhre YouTube-Videos, -Bewertungen, -Kommentare und -Untertitel ansehen, bearbeiten oder dauerhaft löschen
https://www.googleapis.com/auth/youtube.readonlyYouTube-Konto abrufen
https://www.googleapis.com/auth/youtube.uploadYouTube-Videos verwalten
https://www.googleapis.com/auth/youtubepartnerIhre Inhalte und zugehörigen Content bei YouTube abrufen und verwalten
https://www.googleapis.com/auth/youtubepartner-channel-auditPrivate Informationen aus dem YouTube-Kanal abrufen, die während des Prüfprozesses durch einen YouTube-Partner relevant sind

Installierte Apps oder Geräte finden Sie in der Liste Zulässige Bereiche.

OAuth 2.0-Zugriffstokens abrufen

Auch wenn Ihre Anwendung auf einem Gerät mit eingeschränkten Eingabemöglichkeiten ausgeführt wird, benötigen Nutzer einen separaten Zugriff auf ein Gerät mit umfassenderen Eingabefunktionen, um diesen Autorisierungsvorgang abzuschließen. Der Ablauf umfasst die folgenden Schritte:

  1. Ihre Anwendung sendet eine Anfrage an den Autorisierungsserver von Google, die die Bereiche identifiziert, für die Ihre Anwendung die Zugriffsberechtigung anfordert.
  2. Der Server antwortet mit mehreren Informationen, die in den nachfolgenden Schritten verwendet werden, z. B. einem Gerätecode und einem Nutzercode.
  3. Es werden Informationen angezeigt, die der Nutzer zur Autorisierung deiner App auf einem separaten Gerät eingeben kann.
  4. Ihre Anwendung beginnt, den Autorisierungsserver von Google abzufragen, um festzustellen, ob der Nutzer Ihre App autorisiert hat.
  5. Der Nutzer wechselt zu einem Gerät mit umfassenderen Eingabemöglichkeiten, startet einen Webbrowser, ruft die in Schritt 3 angezeigte URL auf und gibt einen Code ein, der auch in Schritt 3 angezeigt wird. Der Nutzer kann dann den Zugriff auf Ihre Anwendung gewähren (oder verweigern).
  6. Die nächste Antwort auf Ihre Abfrageanfrage enthält die Tokens, die Ihre Anwendung zum Autorisieren von Anfragen im Namen des Nutzers benötigt. Wenn der Nutzer den Zugriff auf Ihre Anwendung verweigert hat, enthält die Antwort keine Tokens.

Die folgende Abbildung veranschaulicht diesen Vorgang:

Der Nutzer meldet sich auf einem separaten Gerät mit Browser an.

In den folgenden Abschnitten werden diese Schritte ausführlich erläutert. Aufgrund der zahlreichen Funktionen und Laufzeitumgebungen der Geräte wird in den Beispielen in diesem Dokument das Befehlszeilendienstprogramm curl verwendet. Diese Beispiele sollten einfach in verschiedene Sprachen und Laufzeiten portierbar sein.

Schritt 1: Geräte- und Nutzercodes anfordern

In diesem Schritt sendet dein Gerät eine HTTP-POST-Anfrage an den Autorisierungsserver von Google unter https://oauth2.googleapis.com/device/code. Diese Anfrage identifiziert deine Anwendung sowie die Zugriffsbereiche, auf die deine Anwendung im Namen des Nutzers zugreifen möchte. Rufen Sie diese URL mithilfe des Metadatenwerts device_authorization_endpoint aus dem Discovery-Dokument ab. Geben Sie dabei die folgenden HTTP-Anfrageparameter an:

Parameter
client_id Erforderlich

Die Client-ID für Ihre Anwendung. Sie finden diesen Wert in der API Console- Credentials page.

scope Erforderlich

Eine durch Leerzeichen getrennte Liste von Bereichen, die die Ressourcen angeben, auf die Ihre Anwendung im Namen des Nutzers zugreifen könnte. Diese Werte beziehen sich auf den Zustimmungsbildschirm, den Google dem Nutzer anzeigt. Installierte Apps oder Geräte finden Sie in der Liste Zulässige Bereiche.

Mithilfe von Bereichen kann Ihre Anwendung nur Zugriff auf die Ressourcen anfordern, die sie benötigt. Gleichzeitig ermöglichen sie Nutzern, den Umfang des Zugriffs auf Ihre Anwendung zu steuern. Daher besteht ein umgekehrter Zusammenhang zwischen der Anzahl der angeforderten Bereiche und der Wahrscheinlichkeit, dass die Nutzereinwilligung eingeholt wird.

Die YouTube Data API Version 3 nutzt die folgenden Bereiche:

Sucher
https://www.googleapis.com/auth/youtubeYouTube-Konto verwalten
https://www.googleapis.com/auth/youtube.channel-memberships.creatorEine Liste der aktuell aktiven Mitglieder des Kanals, ihre Stufe und ihr Eintrittsdatum abrufen
https://www.googleapis.com/auth/youtube.force-sslIhre YouTube-Videos, -Bewertungen, -Kommentare und -Untertitel ansehen, bearbeiten oder dauerhaft löschen
https://www.googleapis.com/auth/youtube.readonlyYouTube-Konto abrufen
https://www.googleapis.com/auth/youtube.uploadYouTube-Videos verwalten
https://www.googleapis.com/auth/youtubepartnerIhre Inhalte und zugehörigen Content bei YouTube abrufen und verwalten
https://www.googleapis.com/auth/youtubepartner-channel-auditPrivate Informationen aus dem YouTube-Kanal abrufen, die während des Prüfprozesses durch einen YouTube-Partner relevant sind

Das Dokument OAuth 2.0-API-Bereiche enthält eine vollständige Liste der Bereiche, die Sie für den Zugriff auf Google APIs verwenden können.

Beispiele

Das folgende Snippet zeigt eine Beispielanfrage:

POST /device/code HTTP/1.1
Host: oauth2.googleapis.com
Content-Type: application/x-www-form-urlencoded

client_id=client_id&scope=https%3A%2F%2Fwww.googleapis.com%2Fauth%2Fyoutube.force-ssl

Dieses Beispiel zeigt einen curl-Befehl zum Senden derselben Anfrage:

curl -d "client_id=client_id&scope=https%3A%2F%2Fwww.googleapis.com%2Fauth%2Fyoutube.force-ssl" \
     https://oauth2.googleapis.com/device/code

Schritt 2: Antwort des Autorisierungsservers verarbeiten

Der Autorisierungsserver gibt eine der folgenden Antworten zurück:

Erfolgsantwort

Wenn die Anfrage gültig ist, ist die Antwort ein JSON-Objekt mit den folgenden Attributen:

Attribute
device_code Wert, den Google eindeutig zuweist, um das Gerät zu identifizieren, auf dem die App ausgeführt wird, die die Autorisierung anfordert. Der Nutzer autorisiert dieses Gerät von einem anderen Gerät mit umfassenderen Eingabemöglichkeiten. Beispielsweise kann ein Nutzer einen Laptop oder ein Smartphone verwenden, um eine App zu autorisieren, die auf einem Fernseher ausgeführt wird. In diesem Fall identifiziert die device_code den Fernseher.

Mit diesem Code kann das Gerät, auf dem die App ausgeführt wird, auf sichere Weise ermitteln, ob der Nutzer den Zugriff gewährt oder verweigert hat.

expires_in Die Dauer in Sekunden, für die device_code und user_code gültig sind. Wenn der Nutzer in dieser Zeit den Autorisierungsvorgang nicht abschließt und dein Gerät keine Informationen über die Entscheidung des Nutzers abruft, musst du diesen Prozess möglicherweise ab Schritt 1 neu starten.
interval Die Zeit in Sekunden, die Ihr Gerät zwischen Abfrageanfragen warten soll. Wenn der Wert beispielsweise 5 ist, sollte Ihr Gerät alle fünf Sekunden eine Abfrageanfrage an den Autorisierungsserver von Google senden. Weitere Informationen finden Sie in Schritt 3.
user_code Ein Wert, bei dem die Groß- und Kleinschreibung berücksichtigt wird und der für Google die Bereiche identifiziert, für die die Anwendung Zugriff anfordert. Über die Benutzeroberfläche wird der Nutzer aufgefordert, diesen Wert auf einem separaten Gerät mit umfassenderen Eingabemöglichkeiten einzugeben. Google verwendet diesen Wert dann, um den richtigen Bereich anzuzeigen, wenn der Nutzer aufgefordert wird, Zugriff auf Ihre Anwendung zu gewähren.
verification_url Eine URL, zu der der Nutzer auf einem anderen Gerät gehen muss, um die user_code einzugeben und Zugriff auf Ihre Anwendung zu gewähren oder zu verweigern. Auf der Benutzeroberfläche wird dieser Wert ebenfalls angezeigt.

Das folgende Snippet zeigt eine Beispielantwort:

{
  "device_code": "4/4-GMMhmHCXhWEzkobqIHGG_EnNYYsAkukHspeYUk9E8",
  "user_code": "GQVQ-JKEC",
  "verification_url": "https://www.google.com/device",
  "expires_in": 1800,
  "interval": 5
}

Antwort zu Kontingentüberschreitung

Wenn Ihre Gerätecodeanfragen das mit Ihrer Client-ID verknüpfte Kontingent überschritten haben, erhalten Sie eine 403-Antwort mit dem folgenden Fehler:

{
  "error_code": "rate_limit_exceeded"
}

Verwenden Sie in diesem Fall eine Backoff-Strategie, um die Anfragerate zu reduzieren.

Schritt 3: Nutzercode anzeigen

Zeige dem Nutzer die in Schritt 2 abgerufenen verification_url und user_code an. Beide Werte können beliebige druckbare Zeichen aus dem US-ASCII-Zeichensatz enthalten. Der Inhalt, den du dem Nutzer vorstellst, sollte ihn anweisen, auf einem anderen Gerät zum verification_url zu gehen und den user_code einzugeben.

Beachten Sie beim Entwerfen Ihrer Benutzeroberfläche (UI) folgende Regeln:

  • user_code
    • user_code muss in einem Feld angezeigt werden, das 15 Zeichen der Größe „W“ verarbeiten kann. Mit anderen Worten: Wenn sich der Code WWWWWWWWWWWWWWW korrekt anzeigen lässt, ist Ihre UI gültig. Wir empfehlen, diesen Stringwert zu verwenden, wenn Sie testen, wie user_code in Ihrer UI angezeigt wird.
    • Bei user_code wird zwischen Groß- und Kleinschreibung unterschieden und es sollte in keiner Weise geändert werden, z. B. durch Ändern der Groß-/Kleinschreibung oder Einfügen anderer Formatierungszeichen.
  • verification_url
    • Der Bereich für die verification_url muss so breit sein, dass ein URL-String mit einer Länge von 40 Zeichen verarbeitet werden kann.
    • Sie sollten verification_url in keiner Weise ändern, es sei denn, Sie möchten das anzuzeigende Schema entfernen. Wenn du das Schema (z.B. https://) aus Anzeigegründen aus der URL entfernen möchtest, muss deine App sowohl http- als auch https-Varianten verarbeiten können.

Schritt 4: Autorisierungsserver von Google abfragen

Da der Nutzer ein separates Gerät verwendet, um verification_url aufzurufen und den Zugriff zu gewähren (oder abzulehnen), wird das anfordernde Gerät nicht automatisch benachrichtigt, wenn der Nutzer auf die Zugriffsanfrage reagiert. Aus diesem Grund muss das anfragende Gerät den Autorisierungsserver von Google abfragen, um festzustellen, wann der Nutzer auf die Anfrage geantwortet hat.

Das anfragende Gerät sollte so lange Abfrageanfragen senden, bis es eine Antwort erhält, die besagt, dass der Nutzer auf die Zugriffsanfrage reagiert hat, oder bis die in Schritt 2 abgerufenen device_code und user_code abgelaufen sind. Der in Schritt 2 zurückgegebene interval gibt die Zeitspanne in Sekunden an, die zwischen Anfragen gewartet werden soll.

Die URL des abzufragenden Endpunkts lautet https://oauth2.googleapis.com/token. Die Abfrageanfrage enthält die folgenden Parameter:

Parameter
client_id Die Client-ID für Ihre Anwendung. Sie finden diesen Wert in der API Console- Credentials page.
client_secret Der Clientschlüssel für die angegebene client_id. Sie finden diesen Wert in der API Console- Credentials page.
device_code Die device_code, die in Schritt 2 vom Autorisierungsserver zurückgegeben wurde.
grant_type Setzen Sie diesen Wert auf urn:ietf:params:oauth:grant-type:device_code.

Beispiele

Das folgende Snippet zeigt eine Beispielanfrage:

POST /token HTTP/1.1
Host: oauth2.googleapis.com
Content-Type: application/x-www-form-urlencoded

client_id=client_id&
client_secret=client_secret&
device_code=device_code&
grant_type=urn%3Aietf%3Aparams%3Aoauth%3Agrant-type%3Adevice_code

Dieses Beispiel zeigt einen curl-Befehl zum Senden derselben Anfrage:

curl -d "client_id=client_id&client_secret=client_secret& \
         device_code=device_code& \
         grant_type=urn%3Aietf%3Aparams%3Aoauth%3Agrant-type%3Adevice_code" \
         -H "Content-Type: application/x-www-form-urlencoded" \
         https://oauth2.googleapis.com/token

Schritt 5: Nutzer antwortet auf Zugriffsanfrage

Die folgende Abbildung zeigt eine Seite ähnlich der Seite, die Nutzer sehen, wenn sie das in Schritt 3 angezeigte verification_url aufrufen:

Gerät durch Eingabe eines Codes verbinden

Nachdem der Nutzer user_code eingegeben hat und sich bei Google anmeldet, sofern er noch nicht angemeldet ist, wird ein Zustimmungsbildschirm wie unten angezeigt:

Beispiel für einen Zustimmungsbildschirm für einen Geräteclient

Schritt 6: Antworten auf Abfrageanfragen verarbeiten

Der Autorisierungsserver von Google antwortet auf jede Abfrageanfrage mit einer der folgenden Antworten:

Zugriff gewährt

Wenn der Nutzer Zugriff auf das Gerät gewährt hat (durch Klicken auf Allow auf dem Zustimmungsbildschirm), enthält die Antwort ein Zugriffstoken und ein Aktualisierungstoken. Mithilfe der Tokens kann dein Gerät im Namen des Nutzers auf Google APIs zugreifen. Das Attribut scope in der Antwort bestimmt, auf welche APIs das Gerät zugreifen kann.

In diesem Fall enthält die API-Antwort die folgenden Felder:

Felder
access_token Das Token, das Ihre Anwendung zum Autorisieren einer Google API-Anfrage sendet.
expires_in Die verbleibende Lebensdauer des Zugriffstokens in Sekunden.
refresh_token Ein Token, mit dem Sie ein neues Zugriffstoken abrufen können. Aktualisierungstokens sind gültig, bis der Nutzer den Zugriff widerruft. Für Geräte werden Aktualisierungstokens immer zurückgegeben.
scope Die durch den access_token gewährten Zugriffsbereiche, ausgedrückt als Liste mit durch Leerzeichen voneinander getrennten Strings, bei denen die Groß- und Kleinschreibung beachtet wird.
token_type Der Typ des zurückgegebenen Tokens. Derzeit ist der Wert dieses Felds immer auf Bearer festgelegt.

Das folgende Snippet zeigt eine Beispielantwort:

{
  "access_token": "1/fFAGRNJru1FTz70BzhT3Zg",
  "expires_in": 3920,
  "scope": "openid https://www.googleapis.com/auth/userinfo.profile https://www.googleapis.com/auth/userinfo.email",
  "token_type": "Bearer",
  "refresh_token": "1/xEoDL4iW3cxlI7yDbSRFYNG01kVKM2C-259HOF2aQbI"
}

Zugriffstokens haben eine begrenzte Lebensdauer. Wenn die Anwendung über einen längeren Zeitraum Zugriff auf eine API benötigt, kann sie mit dem Aktualisierungstoken ein neues Zugriffstoken abrufen. Wenn Ihre Anwendung diese Art von Zugriff benötigt, sollte sie das Aktualisierungstoken zur späteren Verwendung speichern.

Zugriff verweigert

Wenn der Nutzer den Zugriff auf das Gerät verweigert, enthält die Serverantwort den Statuscode 403 der HTTP-Antwort (Forbidden). Die Antwort enthält den folgenden Fehler:

{
  "error": "access_denied",
  "error_description": "Forbidden"
}

Autorisierung ausstehend

Wenn der Nutzer die Autorisierung noch nicht abgeschlossen hat, gibt der Server den Statuscode 428 der HTTP-Antwort (Precondition Required) zurück. Die Antwort enthält den folgenden Fehler:

{
  "error": "authorization_pending",
  "error_description": "Precondition Required"
}

Wird zu häufig abgefragt

Wenn das Gerät zu häufig Abfrageanfragen sendet, gibt der Server den HTTP-Antwortstatuscode 403 (Forbidden) zurück. Die Antwort enthält den folgenden Fehler:

{
  "error": "slow_down",
  "error_description": "Forbidden"
}

Weitere Fehler

Der Autorisierungsserver gibt auch dann Fehler zurück, wenn in der Abfrageanfrage erforderliche Parameter fehlen oder ein falscher Parameterwert vorhanden ist. Diese Anfragen haben normalerweise den HTTP-Antwortstatuscode 400 (Bad Request) oder 401 (Unauthorized). Zu diesen Fehlern gehören:

Fehler HTTP-Statuscode Beschreibung
admin_policy_enforced 400 Das Google-Konto kann einen oder mehrere angeforderte Bereiche aufgrund der Richtlinien des Google Workspace-Administrators nicht autorisieren. Im Hilfeartikel Zugriff externer und interner Anwendungen auf Google Workspace-Daten verwalten finden Sie weitere Informationen dazu, wie Administratoren den Zugriff auf Bereiche einschränken können, bis der Zugriff für Ihre OAuth-Client-ID explizit gewährt wurde.
invalid_client 401

Der OAuth-Client wurde nicht gefunden. Dieser Fehler tritt beispielsweise auf, wenn der Parameterwert client_id ungültig ist.

Der OAuth-Clienttyp ist falsch. Der Anwendungstyp für die Client-ID muss auf Fernseher und Geräte mit begrenzter Eingabe festgelegt sein.

invalid_grant 400 Der Parameterwert code ist ungültig, wurde bereits beansprucht oder kann nicht geparst werden.
unsupported_grant_type 400 Der Parameterwert grant_type ist ungültig.
org_internal 403 Die OAuth-Client-ID in der Anfrage ist Teil eines Projekts, das den Zugriff auf Google-Konten in einer bestimmten Google Cloud-Organisation einschränkt. Bestätigen Sie die Nutzertypkonfiguration für Ihre OAuth-Anwendung.

Google APIs aufrufen

Nachdem Ihre Anwendung ein Zugriffstoken abgerufen hat, können Sie mit dem Token im Namen eines bestimmten Nutzerkontos eine Google API aufrufen, sofern die von der API erforderlichen Zugriffsbereiche gewährt wurden. Fügen Sie dazu das Zugriffstoken in eine Anfrage an die API ein. Dazu geben Sie entweder den Abfrageparameter access_token oder den Bearer-Wert eines Authorization-HTTP-Headers an. Wenn möglich, sollte der HTTP-Header verwendet werden, da Abfragestrings in der Regel in Serverlogs sichtbar sind. In den meisten Fällen kannst du deine Aufrufe von Google APIs mithilfe einer Clientbibliothek einrichten, z. B. beim Aufruf der YouTube Live Streaming API.

Beachte, dass die YouTube Live Streaming API den Vorgang für Dienstkonten nicht unterstützt. Da es keine Möglichkeit gibt, ein Dienstkonto mit einem YouTube-Konto zu verknüpfen, wird beim Autorisieren von Anfragen mit diesem Ablauf der Fehler NoLinkedYouTubeAccount generiert.

Sie können alle Google APIs testen und ihre Bereiche im OAuth 2.0 Playground ansehen.

HTTP GET-Beispiele

Ein Aufruf des Endpunkts liveBroadcasts.list (die YouTube Live Streaming API) mit dem HTTP-Header Authorization: Bearer könnte so aussehen. Beachten Sie, dass Sie Ihr eigenes Zugriffstoken angeben müssen:

GET /youtube/v3/liveBroadcasts?part=id%2Csnippet&mine=true HTTP/1.1
Host: www.googleapis.com
Authorization: Bearer access_token

Hier ist ein Aufruf derselben API für den authentifizierten Nutzer mit dem Abfragestringparameter access_token:

GET https://www.googleapis.com/youtube/v3/liveBroadcasts?access_token=access_token&part=id%2Csnippet&mine=true

Beispiele für curl

Sie können diese Befehle mit der curl-Befehlszeilenanwendung testen. Hier ein Beispiel, in dem die HTTP-Header-Option (bevorzugt) verwendet wird:

curl -H "Authorization: Bearer access_token" https://www.googleapis.com/youtube/v3/liveBroadcasts?part=id%2Csnippet&mine=true

Alternativ können Sie die Parameteroption für den Abfragestring verwenden:

curl https://www.googleapis.com/youtube/v3/liveBroadcasts?access_token=access_token&part=id%2Csnippet&mine=true

Zugriffstokens aktualisieren

Zugriffstokens laufen regelmäßig ab und werden zu ungültigen Anmeldedaten für eine zugehörige API-Anfrage. Sie können ein Zugriffstoken aktualisieren, ohne den Nutzer um Erlaubnis zu bitten (auch wenn der Nutzer nicht anwesend ist), wenn Sie Offlinezugriff auf die mit dem Token verknüpften Bereiche angefordert haben.

Zum Aktualisieren eines Zugriffstokens sendet die Anwendung eine HTTPS-POST-Anfrage an den Autorisierungsserver von Google (https://oauth2.googleapis.com/token), die die folgenden Parameter enthält:

Felder
client_id Die Client-ID aus API Console.
client_secret Der Clientschlüssel, der aus dem API Consoleabgerufen wurde.
grant_type Wie in der OAuth 2.0-Spezifikation definiert, muss der Wert dieses Felds auf refresh_token festgelegt werden.
refresh_token Das vom Autorisierungscode-Austausch zurückgegebene Aktualisierungstoken

Das folgende Snippet zeigt eine Beispielanfrage:

POST /token HTTP/1.1
Host: oauth2.googleapis.com
Content-Type: application/x-www-form-urlencoded

client_id=your_client_id&
client_secret=your_client_secret&
refresh_token=refresh_token&
grant_type=refresh_token

Solange der Nutzer den der Anwendung gewährten Zugriff nicht widerrufen hat, gibt der Tokenserver ein JSON-Objekt zurück, das ein neues Zugriffstoken enthält. Das folgende Snippet zeigt eine Beispielantwort:

{
  "access_token": "1/fFAGRNJru1FTz70BzhT3Zg",
  "expires_in": 3920,
  "scope": "https://www.googleapis.com/auth/drive.metadata.readonly",
  "token_type": "Bearer"
}

Beachten Sie, dass es Limits für die Anzahl der ausgegebenen Aktualisierungstokens gibt: ein Limit pro Client/Nutzer-Kombination und ein anderes pro Nutzer für alle Clients. Sie sollten Aktualisierungstokens langfristig aufbewahren und so lange verwenden, wie sie gültig sind. Wenn Ihre Anwendung zu viele Aktualisierungstokens anfordert, können diese Limits erreicht werden. In diesem Fall funktionieren ältere Aktualisierungstokens nicht mehr.

Token widerrufen

In manchen Fällen möchte ein Nutzer den Zugriff auf eine App widerrufen. Nutzer können den Zugriff in den Kontoeinstellungen widerrufen. Weitere Informationen findest du im Supportdokument Website- oder App-Zugriff entfernen im Supportdokument von Drittanbietern.

Apps können den ihr gewährten Zugriff auch programmatisch widerrufen. Der programmatische Widerruf ist wichtig, wenn sich ein Nutzer abmeldet, eine Anwendung entfernt oder sich die für eine Anwendung erforderlichen API-Ressourcen erheblich geändert haben. Mit anderen Worten: Ein Teil des Entfernungsprozesses kann eine API-Anfrage umfassen, mit der sichergestellt wird, dass die zuvor der Anwendung gewährten Berechtigungen entfernt werden.

Zum programmatischen Widerrufen eines Tokens sendet Ihre Anwendung eine Anfrage an https://oauth2.googleapis.com/revoke und nimmt das Token als Parameter auf:

curl -d -X -POST --header "Content-type:application/x-www-form-urlencoded" \
        https://oauth2.googleapis.com/revoke?token={token}

Das Token kann ein Zugriffstoken oder ein Aktualisierungstoken sein. Wenn das Token ein Zugriffstoken ist und ein entsprechendes Aktualisierungstoken vorhanden ist, wird auch das Aktualisierungstoken widerrufen.

Wenn der Widerruf erfolgreich verarbeitet wurde, lautet der HTTP-Statuscode der Antwort 200. Bei Fehlerbedingungen wird der HTTP-Statuscode 400 zusammen mit einem Fehlercode zurückgegeben.

Zulässige Bereiche

Der OAuth 2.0-Vorgang für Geräte wird nur für die folgenden Bereiche unterstützt:

OpenID Connect, Google Log-in

  • email
  • openid
  • profile

Drive API

  • https://www.googleapis.com/auth/drive.appdata
  • https://www.googleapis.com/auth/drive.file

YouTube API

  • https://www.googleapis.com/auth/youtube
  • https://www.googleapis.com/auth/youtube.readonly