Korzystanie z protokołu OAuth 2.0 w aplikacjach internetowych JavaScript

Z tego artykułu dowiesz się, jak wdrożyć autoryzację OAuth 2.0, aby uzyskać dostęp do interfejsu YouTube Analytics API lub YouTube Reporting API w aplikacji internetowej JavaScript. Protokół OAuth 2.0 pozwala użytkownikom udostępniać określone dane aplikacji przy zachowaniu prywatności nazw użytkowników, haseł i innych informacji. Aplikacja może na przykład korzystać z protokołu OAuth 2.0, aby uzyskać uprawnienia do pobierania danych ze Statystyk YouTube dotyczących kanału.

Ten przepływ OAuth 2.0 jest nazywany przepływem niejawnym. Jest przeznaczony dla aplikacji, które uzyskują dostęp do interfejsów API tylko wtedy, gdy użytkownik jest obecny w aplikacji. Takie aplikacje nie mogą przechowywać poufnych informacji.

W tym procesie aplikacja otwiera adres URL Google, który używa parametrów zapytania do identyfikacji aplikacji oraz typu dostępu do interfejsu API, którego wymaga aplikacja. Możesz otworzyć adres URL w bieżącym oknie przeglądarki lub w wyskakującym okienku. Użytkownik może uwierzytelnić się w Google i przyznać mu wymagane uprawnienia. Następnie Google przekierowuje użytkownika z powrotem do Twojej aplikacji. Przekierowanie zawiera token dostępu, który jest weryfikowany przez aplikację, a następnie używany do wysyłania żądań do interfejsu API.

Biblioteka klienta interfejsów API Google i usługi tożsamości Google

Jeśli do wykonywania autoryzowanych wywołań do Google używasz biblioteki klienta interfejsów API Google dla JavaScript, do obsługi procesu OAuth 2.0 musisz użyć biblioteki JavaScript usług tożsamości Google. Sprawdź model tokena usług tożsamości Google oparty na przepływie niejawnego uwierzytelniania OAuth 2.0.

Wymagania wstępne

Włącz interfejsy API w projekcie

Każda aplikacja wywołująca interfejsy API Google musi włączyć te interfejsy API w: API Console.

Aby włączyć interfejs API w projekcie:

  1. Open the API Library w: Google API Console.
  2. If prompted, select a project, or create a new one.
  3. Na stronie Biblioteka znajdź i włącz interfejsy YouTube Analytics API oraz YouTube Reporting API. Wiele aplikacji, które pobierają dane ze Statystyk YouTube, również współpracuje z interfejsem YouTube Data API. Znajdź wszystkie inne interfejsy API, których będzie używać Twoja aplikacja, i je włącz.

Tworzenie danych uwierzytelniających

Każda aplikacja korzystająca z OAuth 2.0 do uzyskiwania dostępu do interfejsów API Google musi mieć dane uwierzytelniające, które identyfikują aplikację z serwerem Google OAuth 2.0. Podane niżej kroki wyjaśniają, jak utworzyć dane logowania w projekcie. Aplikacje mogą dzięki temu używać tych danych logowania, aby uzyskiwać dostęp do interfejsów API włączonych w danym projekcie.

  1. Go to the Credentials page.
  2. Kliknij Utwórz dane logowania > Identyfikator klienta OAuth.
  3. Wybierz typ aplikacji Aplikacja internetowa.
  4. Wypełnij formularz. Aplikacje, które używają JavaScriptu do wykonywania autoryzowanych żądań do interfejsu API Google, muszą mieć autoryzowane źródła JavaScript. Źródła identyfikują domeny, z których Twoja aplikacja może wysyłać żądania do serwera OAuth 2.0. Takie źródła muszą być zgodne z regułami weryfikacji Google.

Identyfikowanie zakresów dostępu

Zakresy umożliwiają aplikacji żądanie dostępu tylko do potrzebnych zasobów, a jednocześnie pozwalają użytkownikom kontrolować zakres dostępu, który przyznają aplikacji. Z tego powodu może występować odwrotny związek między liczbą żądanych zakresów a prawdopodobieństwem uzyskania zgody użytkownika.

Przed rozpoczęciem implementacji autoryzacji OAuth 2.0 zalecamy wskazanie zakresów, do których aplikacja będzie potrzebować uprawnień.

Interfejs YouTube Analytics API używa tych zakresów:

Zakresy
https://www.googleapis.com/auth/youtube Zarządzaj swoim kontem YouTube
https://www.googleapis.com/auth/youtube.readonly Wyświetl swoje konto YouTube
https://www.googleapis.com/auth/youtubepartner Wyświetlaj swoje zasoby i powiązane treści w YouTube oraz zarządzaj nimi
https://www.googleapis.com/auth/yt-analytics-monetary.readonly Wyświetlaj finansowe i niepieniężne raporty YouTube Analytics dotyczące treści w YouTube
https://www.googleapis.com/auth/yt-analytics.readonly Wyświetlaj raporty YouTube Analytics dotyczące swoich treści w YouTube

Interfejs YouTube Reporting API używa tych zakresów:

Zakresy
https://www.googleapis.com/auth/yt-analytics-monetary.readonly Wyświetlaj finansowe i niepieniężne raporty YouTube Analytics dotyczące treści w YouTube
https://www.googleapis.com/auth/yt-analytics.readonly Wyświetlaj raporty YouTube Analytics dotyczące swoich treści w YouTube

Dokument Zakresy interfejsów API OAuth 2.0 zawiera pełną listę zakresów, których możesz używać do uzyskiwania dostępu do interfejsów API Google.

Uzyskiwanie tokenów dostępu OAuth 2.0

Poniższe kroki pokazują, jak Twoja aplikacja współpracuje z serwerem Google OAuth 2.0, aby uzyskać zgodę użytkownika na wykonanie żądania do interfejsu API w jego imieniu. Twoja aplikacja musi uzyskać taką zgodę, zanim będzie mogła wykonywać żądanie do interfejsu API Google wymagające autoryzacji użytkownika.

Krok 1. Przekieruj na serwer Google OAuth 2.0

Aby poprosić o dostęp do danych użytkownika, przekieruj go na serwer Google OAuth 2.0.

Punkty końcowe OAuth 2.0

Wygeneruj adres URL, aby poprosić o dostęp z punktu końcowego OAuth 2.0 Google pod adresem https://accounts.google.com/o/oauth2/v2/auth. Ten punkt końcowy jest dostępny przez HTTPS. Zwykłe połączenia HTTP są odrzucane.

Serwer autoryzacji Google obsługuje następujące parametry ciągu zapytania dla aplikacji serwera WWW:

Parametry
client_id Wymagane

Identyfikator klienta aplikacji. Tę wartość znajdziesz w API Console Credentials page.

redirect_uri Wymagane

Określa, gdzie serwer interfejsu API przekierowuje użytkownika po zakończeniu procesu autoryzacji. Wartość musi być dokładnie taka sama jak jeden z autoryzowanych identyfikatorów URI przekierowania klienta OAuth 2.0 skonfigurowanych w pliku API Console Credentials pageklienta. Jeśli ta wartość nie jest zgodna z autoryzowanym identyfikatorem URI przekierowania dla podanego identyfikatora client_id, wystąpi błąd redirect_uri_mismatch.

Schemat http lub https, wielkość liter i ukośnik końcowy („/”) muszą być zgodne.

response_type Wymagane

Aplikacje JavaScript muszą ustawić wartość parametru na token. Ta wartość nakazuje serwerowi autoryzacji Google zwracanie tokena dostępu w postaci pary name=value w identyfikatorze fragmentu kodu URI (#), do którego użytkownik jest przekierowywany po zakończeniu procesu autoryzacji.

scope Wymagane

Rozdzielona spacjami lista zakresów identyfikujących zasoby, do których aplikacja może uzyskiwać dostęp w imieniu użytkownika. Wartości te informują o ekranie zgody wyświetlanym przez Google użytkownikowi.

Zakresy umożliwiają aplikacji żądanie dostępu tylko do potrzebnych zasobów, a także pozwalają użytkownikom kontrolować zakres dostępu, który przyznają aplikacji. Dlatego istnieje odwrotny zależność między liczbą żądanych zakresów a prawdopodobieństwem uzyskania zgody użytkownika.

Interfejs YouTube Analytics API używa tych zakresów:

Zakresy
https://www.googleapis.com/auth/youtube Zarządzaj swoim kontem YouTube
https://www.googleapis.com/auth/youtube.readonly Wyświetl swoje konto YouTube
https://www.googleapis.com/auth/youtubepartner Wyświetlaj swoje zasoby i powiązane treści w YouTube oraz zarządzaj nimi
https://www.googleapis.com/auth/yt-analytics-monetary.readonly Wyświetlaj finansowe i niepieniężne raporty YouTube Analytics dotyczące treści w YouTube
https://www.googleapis.com/auth/yt-analytics.readonly Wyświetlaj raporty YouTube Analytics dotyczące swoich treści w YouTube

Interfejs YouTube Reporting API używa tych zakresów:

Zakresy
https://www.googleapis.com/auth/yt-analytics-monetary.readonly Wyświetlaj finansowe i niepieniężne raporty YouTube Analytics dotyczące treści w YouTube
https://www.googleapis.com/auth/yt-analytics.readonly Wyświetlaj raporty YouTube Analytics dotyczące swoich treści w YouTube

Dokument Zakresy interfejsów API OAuth 2.0 zawiera pełną listę zakresów, których możesz używać do uzyskiwania dostępu do interfejsów API Google.

Zalecamy, aby aplikacja prosiła o dostęp do zakresów autoryzacji w kontekście, gdy jest to możliwe. Wysyłając prośbę o dostęp do danych użytkownika w kontekście za pomocą dodatkowej autoryzacji, pomagasz użytkownikom zrozumieć, dlaczego aplikacja potrzebuje dostępu, o który prosi.

state Zalecane

Określa dowolną wartość ciągu znaków używaną przez aplikację do utrzymywania stanu między żądaniem autoryzacji a odpowiedzią serwera autoryzacji. Serwer zwraca dokładną wartość, którą wysyłasz jako parę name=value w identyfikatorze fragmentu adresu URL (#) parametru redirect_uri, gdy użytkownik wyrazi zgodę na dostęp aplikacji lub go odrzuci.

Możesz używać tego parametru do różnych celów, np. do przekierowywania użytkownika do odpowiedniego zasobu w aplikacji, wysyłania liczb jednorazowych i łagodzenia fałszowania żądań między witrynami. Ponieważ redirect_uri można odgadnąć, użycie wartości state może zwiększyć pewność, że połączenie przychodzące jest wynikiem żądania uwierzytelnienia. Jeśli wygenerujesz losowy ciąg znaków lub zakodujesz skrót pliku cookie bądź inną wartość, która przechwytuje stan klienta, możesz dodatkowo zweryfikować odpowiedź, by dodatkowo upewnić się, że żądanie i odpowiedź pochodzą z tej samej przeglądarki. Zabezpiecza to przed atakami, takimi jak fałszowanie żądań z innych witryn. Przykład tego, jak utworzyć i potwierdzić token state, znajdziesz w dokumentacji OpenID Connect.

include_granted_scopes Opcjonalny

Umożliwia aplikacjom korzystanie z autoryzacji przyrostowej do żądania dostępu do dodatkowych zakresów w kontekście. Jeśli ustawisz wartość tego parametru na true i żądanie autoryzacji zostanie zaakceptowane, nowy token dostępu będzie też obejmować wszystkie zakresy, do których użytkownik wcześniej przyznał dostęp do aplikacji. Przykłady znajdziesz w sekcji autoryzacja przyrostowa.

login_hint Opcjonalny

Jeśli aplikacja wie, który użytkownik próbuje się uwierzytelnić, może użyć tego parametru, aby podać wskazówkę dla serwera uwierzytelniania Google. Serwer wykorzystuje wskazówkę, aby uprościć proces logowania, wstępnie wypełniając pole adresu e-mail w formularzu logowania lub wybierając odpowiednią sesję wielokrotnego logowania.

Ustaw wartość parametru na adres e-mail lub identyfikator sub, który odpowiada identyfikatorowi Google użytkownika.

prompt Opcjonalny

Rozdzielona spacjami lista promptów dla użytkownika (z uwzględnieniem wielkości liter). Jeśli nie określisz tego parametru, użytkownik zobaczy pytanie tylko wtedy, gdy projekt poprosi o dostęp po raz pierwszy. Więcej informacji znajdziesz w artykule o prośbie o ponowne wyrażenie zgody.

Możliwe wartości to:

none Nie wyświetlaj żadnych ekranów uwierzytelniania ani zgody. Nie może zawierać innych wartości.
consent Wyświetlaj użytkownikowi prośbę o zgodę.
select_account Zachęć użytkownika do wybrania konta.

Przykładowe przekierowanie na serwer autoryzacji Google

Poniższy przykładowy URL prosi o dostęp offline (access_type=offline) do zakresu, który umożliwia pobieranie raportów Statystyk YouTube użytkownika. Wykorzystuje autoryzację przyrostową, aby mieć pewność, że nowy token dostępu obejmuje wszystkie zakresy, do których użytkownik wcześniej przyznał dostęp do aplikacji. Adres URL ustawia też wartości wymaganych parametrów redirect_uri, response_type i client_id oraz state. Adres URL zawiera podziały wierszy i spacje, aby zwiększyć czytelność.

https://accounts.google.com/o/oauth2/v2/auth?
 scope=https%3A%2F%2Fwww.googleapis.com%2Fauth%2Fyt-analytics.readonly&
 include_granted_scopes=true&
 state=state_parameter_passthrough_value&
 redirect_uri=http%3A%2F%2Flocalhost%2Foauth2callback&
 response_type=token&
 client_id=client_id

Po utworzeniu adresu URL żądania przekieruj na niego użytkownika.

Przykładowy kod JavaScript

Poniższy fragment kodu JavaScript pokazuje, jak rozpocząć proces autoryzacji w JavaScripcie bez używania biblioteki klienta interfejsów API Google do obsługi JavaScriptu. Ponieważ ten punkt końcowy OAuth 2.0 nie obsługuje udostępniania zasobów między serwerami (CORS), fragment kodu tworzy formularz, który otwiera żądanie do tego punktu końcowego.

/*
 * Create form to request access token from Google's OAuth 2.0 server.
 */
function oauthSignIn() {
  // Google's OAuth 2.0 endpoint for requesting an access token
  var oauth2Endpoint = 'https://accounts.google.com/o/oauth2/v2/auth';

  // Create <form> element to submit parameters to OAuth 2.0 endpoint.
  var form = document.createElement('form');
  form.setAttribute('method', 'GET'); // Send as a GET request.
  form.setAttribute('action', oauth2Endpoint);

  // Parameters to pass to OAuth 2.0 endpoint.
  var params = {'client_id': 'YOUR_CLIENT_ID',
                'redirect_uri': 'YOUR_REDIRECT_URI',
                'response_type': 'token',
                'scope': 'https://www.googleapis.com/auth/yt-analytics.readonly',
                'include_granted_scopes': 'true',
                'state': 'pass-through value'};

  // Add form parameters as hidden input values.
  for (var p in params) {
    var input = document.createElement('input');
    input.setAttribute('type', 'hidden');
    input.setAttribute('name', p);
    input.setAttribute('value', params[p]);
    form.appendChild(input);
  }

  // Add form to page and submit it to open the OAuth 2.0 endpoint.
  document.body.appendChild(form);
  form.submit();
}

Krok 2. Google prosi użytkownika o zgodę

W tym kroku użytkownik decyduje, czy przyznać aplikacji żądany dostęp. Na tym etapie Google wyświetla okno zgody z nazwą aplikacji i usług Google API, do których chce uzyskać dostęp, za pomocą danych uwierzytelniających użytkownika. Zawiera też podsumowanie zakresów przyznanych dostępu. Użytkownik może następnie zgodzić się na przyznanie dostępu do co najmniej 1 zakresu żądanego przez Twoją aplikację lub odrzucić żądanie.

Na tym etapie aplikacja nie musi nic robić, ponieważ czeka na odpowiedź serwera Google OAuth 2.0 z informacją o przyznaniu dostępu. Tę odpowiedź wyjaśnimy poniżej.

Błędy

Żądania wysyłane do punktu końcowego autoryzacji OAuth 2.0 Google mogą wyświetlać komunikaty o błędach, które widzą użytkownicy, zamiast oczekiwanych przepływów uwierzytelniania i autoryzacji. Poniżej znajdziesz typowe kody błędów i sugerowane rozwiązania.

admin_policy_enforced

Na koncie Google nie można autoryzować co najmniej jednego żądanego zakresu z powodu zasad jego administratora Google Workspace. Przeczytaj artykuł w Centrum pomocy Google Workspace dla administratorów Określanie, które aplikacje innych firm i aplikacje wewnętrzne mają dostęp do danych Google Workspace, aby dowiedzieć się więcej o tym, jak administrator może ograniczać dostęp do wszystkich zakresów albo do zakresów wrażliwych i zakresów z ograniczeniami, dopóki nie zostanie wyraźnie przyznany dostęp do Twojego identyfikatora klienta OAuth.

disallowed_useragent

Punkt końcowy autoryzacji jest wyświetlany wewnątrz osadzonego klienta użytkownika niedozwolony przez zasady OAuth 2.0 Google.

Android

Deweloperzy aplikacji na Androida mogą napotkać ten komunikat o błędzie podczas otwierania żądań autoryzacji w zadaniu android.webkit.WebView. Deweloperzy powinni zamiast nich używać bibliotek Androida, takich jak Google Sign-In for Android czy AppAuth for Android fundacji OpenID Foundation.

Ten błąd może wystąpić, gdy aplikacja na Androida otwiera ogólny link internetowy we wbudowanym kliencie użytkownika, a użytkownik przechodzi z Twojej witryny do punktu końcowego autoryzacji OAuth 2.0 Google. Deweloperzy powinni zezwolić na otwieranie ogólnych linków w domyślnym module obsługi linków w systemie operacyjnym, który obejmuje zarówno moduły obsługi linków aplikacji na Androida, jak i domyślną aplikację przeglądarki. Obsługiwana jest też biblioteka kart niestandardowych na Androida.

iOS

Deweloperzy aplikacji na iOS i macOS mogą napotkać ten błąd podczas otwierania żądań autoryzacji w zadaniu WKWebView. Deweloperzy powinni zamiast tego używać bibliotek iOS, takich jak Google Sign-In for iOS czy AppAuth for iOS OpenID Foundation.

Programiści stron internetowych mogą napotkać ten błąd, gdy aplikacja na iOS lub macOS otwiera ogólny link internetowy w osadzonym kliencie użytkownika, a użytkownik przechodzi z Twojej witryny do punktu końcowego autoryzacji OAuth 2.0 Google. Deweloperzy powinni zezwolić na otwieranie ogólnych linków w domyślnym module obsługi linków systemu operacyjnego, który uwzględnia zarówno moduły obsługi uniwersalnych linków, jak i domyślną aplikację przeglądarki. Obsługiwana jest też biblioteka SFSafariViewController.

org_internal

Identyfikator klienta OAuth w żądaniu jest częścią projektu ograniczającego dostęp do kont Google w określonej organizacji Google Cloud. Więcej informacji o tej opcji konfiguracji znajdziesz w sekcji Typ użytkownika artykułu pomocy Konfigurowanie ekranu zgody OAuth.

invalid_client

Źródło, z którego wysłano żądanie, nie jest autoryzowane dla tego klienta. Zobacz origin_mismatch.

invalid_grant

Podczas korzystania z autoryzacji przyrostowej token mógł wygasnąć lub został unieważniony. Uwierzytelnij ponownie użytkownika i poproś o zgodę na uzyskanie nowych tokenów. Jeśli ten błąd będzie się powtarzał, sprawdź, czy aplikacja została skonfigurowana poprawnie oraz czy w żądaniu używasz prawidłowych tokenów i parametrów. Jeśli tego nie zrobisz, konto użytkownika mogło zostać usunięte lub wyłączone.

origin_mismatch

Schemat, domena lub port JavaScriptu, z którego pochodzi żądanie autoryzacji, mogą nie być zgodne z autoryzowanym identyfikatorem URI źródła JavaScript zarejestrowanym dla identyfikatora klienta OAuth. Sprawdź autoryzowane źródła JavaScriptu w: Google API Console Credentials page.

redirect_uri_mismatch

Element redirect_uri przekazany w żądaniu autoryzacji nie pasuje do autoryzowanego identyfikatora URI przekierowania dla identyfikatora klienta OAuth. Sprawdź autoryzowane identyfikatory URI przekierowania w pliku Google API Console Credentials page.

Schemat, domena lub port JavaScriptu, z którego pochodzi żądanie autoryzacji, mogą nie być zgodne z autoryzowanym identyfikatorem URI źródła JavaScript zarejestrowanym dla identyfikatora klienta OAuth. Sprawdź autoryzowane źródła JavaScriptu w pliku Google API Console Credentials page.

Parametr redirect_uri może odnosić się do poza zakresem protokołu OAuth (OOB), który został wycofany i nie jest już obsługiwany. Informacje o tym, jak zaktualizować integrację, znajdziesz w przewodniku po migracji.

invalid_request

Coś poszło nie tak z przesłaną przez Ciebie prośbą. Istnieje kilka możliwych przyczyn:

  • Żądanie nie było prawidłowo sformatowane
  • W żądaniu brakuje wymaganych parametrów
  • Żądanie używa metody autoryzacji, która nie jest obsługiwana przez Google. Sprawdź, czy integracja OAuth używa zalecanej metody integracji

Krok 3. Przetwórz odpowiedź serwera OAuth 2.0

Punkty końcowe OAuth 2.0

Serwer OAuth 2.0 wysyła odpowiedź na żądanie redirect_uri określone w żądaniu tokena dostępu.

Jeśli użytkownik zatwierdzi żądanie, odpowiedź będzie zawierać token dostępu. Jeśli użytkownik nie zatwierdzi żądania, odpowiedź będzie zawierać komunikat o błędzie. Token dostępu lub komunikat o błędzie jest zwracany we fragmencie z krzyżykiem identyfikatora URI przekierowania, jak w tym przykładzie:

  • Odpowiedź tokena dostępu:

    https://oauth2.example.com/callback#access_token=4/P7q7W91&token_type=Bearer&expires_in=3600

    Oprócz parametru access_token ciąg fragmentu zawiera też parametr token_type, który jest zawsze ustawiony na Bearer, oraz parametr expires_in, który określa czas życia tokena w sekundach. Jeśli w żądaniu tokena dostępu określono parametr state, jego wartość także zostanie uwzględniona w odpowiedzi.

  • Odpowiedź na błąd:
    https://oauth2.example.com/callback#error=access_denied

Przykładowa odpowiedź serwera OAuth 2.0

Możesz przetestować ten proces, klikając poniższy przykładowy URL, który poprosi o dostęp tylko do odczytu do wyświetlania metadanych plików na Dysku Google:

https://accounts.google.com/o/oauth2/v2/auth?
 scope=https%3A%2F%2Fwww.googleapis.com%2Fauth%2Fyt-analytics.readonly&
 include_granted_scopes=true&
 state=state_parameter_passthrough_value&
 redirect_uri=http%3A%2F%2Flocalhost%2Foauth2callback&
 response_type=token&
 client_id=client_id

Po zakończeniu procesu dotyczącego OAuth 2.0 przekierujemy Cię do http://localhost/oauth2callback. Ten adres URL zwróci błąd 404 NOT FOUND, chyba że komputer lokalny wyświetli plik pod tym adresem. W następnym kroku znajdziesz więcej informacji o informacjach zwracanych w identyfikatorze URI, gdy użytkownik zostanie przekierowany z powrotem do Twojej aplikacji.

wywoływanie interfejsów API Google,

Punkty końcowe OAuth 2.0

Gdy aplikacja uzyska token dostępu, możesz za jego pomocą wywoływać interfejs API Google w imieniu danego konta użytkownika, o ile został przyznany zakres dostępu wymagany przez interfejs API. Aby to zrobić, umieść token dostępu w żądaniu wysyłanym do interfejsu API, uwzględniając parametr zapytania access_token lub wartość nagłówka HTTP Authorization Bearer. W miarę możliwości preferowany jest nagłówek HTTP, ponieważ ciągi zapytań są zazwyczaj widoczne w logach serwera. W większości przypadków możesz skonfigurować wywołania interfejsów API Google za pomocą biblioteki klienta (np. podczas wywoływania interfejsu YouTube Analytics API).

Pamiętaj, że YouTube Analytics API nie obsługuje procesu tworzenia konta usługi. Interfejs YouTube Reporting API obsługuje konta usługi tylko dla właścicieli treści YouTube, którzy są właścicielami wielu kanałów YouTube i zarządzają nimi, np. wytwórniami płytowymi i studiami filmowymi.

Możesz wypróbować wszystkie interfejsy API Google i wyświetlić ich zakresy w narzędziu OAuth 2.0 Playground.

Przykłady HTTP GET

Wywołanie punktu końcowego reports.query (YouTube Analytics API) za pomocą nagłówka HTTP Authorization: Bearer może wyglądać tak. Pamiętaj, że musisz określić własny token dostępu:

GET /youtube/analytics/v1/reports?ids=channel%3D%3DMINE&start-date=2016-05-01&end-date=2016-06-30&metrics=views HTTP/1.1
Host: www.googleapis.com
Authorization: Bearer access_token

Oto wywołanie tego samego interfejsu API dla uwierzytelnionego użytkownika za pomocą parametru ciągu zapytania access_token:

GET https://www.googleapis.com/youtube/analytics/v1/reports?access_token=access_token&ids=channel%3D%3DMINE&start-date=2016-05-01&end-date=2016-06-30&metrics=views

Przykłady zapytań z operatorem curl

Możesz przetestować te polecenia za pomocą aplikacji wiersza poleceń curl. Oto przykład, w którym użyto opcji nagłówka HTTP (preferowana):

curl -H "Authorization: Bearer access_token" https://www.googleapis.com/youtube/analytics/v1/reports?ids=channel%3D%3DMINE&start-date=2016-05-01&end-date=2016-06-30&metrics=views

Możesz też użyć opcji parametrów ciągu zapytania:

curl https://www.googleapis.com/youtube/analytics/v1/reports?access_token=access_token&ids=channel%3D%3DMINE&start-date=2016-05-01&end-date=2016-06-30&metrics=views

Przykładowy kod JavaScript

Fragment kodu poniżej pokazuje, jak za pomocą CORS (współdzielenia zasobów między domenami) wysłać żądanie do interfejsu Google API. W tym przykładzie nie wykorzystano biblioteki klienta interfejsów API Google dla JavaScriptu. Nawet jeśli nie korzystasz z biblioteki klienta, przewodnik pomocy CORS w dokumentacji tej biblioteki prawdopodobnie pomoże Ci lepiej zrozumieć te żądania.

W tym fragmencie kodu zmienna access_token reprezentuje token uzyskany, aby wysyłać żądania do interfejsu API w imieniu autoryzowanego użytkownika. Pełny przykład pokazuje, jak zapisać ten token w lokalnej pamięci przeglądarki i pobrać go podczas wykonywania żądania do interfejsu API.

var xhr = new XMLHttpRequest();
xhr.open('GET',
    'https://www.googleapis.com/youtube/analytics/v1/reports?ids=channel%3D%3DMINE&start-date=2016-05-01&end-date=2016-06-30&metrics=views&' +
    'access_token=' + params['access_token']);
xhr.onreadystatechange = function (e) {
  console.log(xhr.response);
};
xhr.send(null);

Pełny przykład

Punkty końcowe OAuth 2.0

Ten przykładowy kod pokazuje, jak wykonać przepływ OAuth 2.0 w JavaScript bez korzystania z biblioteki klienta interfejsów API Google do JavaScript. Kod jest przeznaczony do strony HTML, która wyświetla przycisk umożliwiający wykonanie żądania do interfejsu API. Jeśli klikniesz przycisk, kod sprawdza, czy strona zapisała token dostępu API w pamięci lokalnej przeglądarki. Jeśli tak, wykona żądanie do interfejsu API. W przeciwnym razie inicjuje proces OAuth 2.0.

W przypadku protokołu OAuth 2.0 strona wykonuje te czynności:

  1. Przekierowanie użytkownika do serwera OAuth 2.0 Google, który żąda dostępu do zakresu https://www.googleapis.com/auth/yt-analytics.readonly.
  2. Po przyznaniu (lub odmowie) dostępu do co najmniej jednego żądanego zakresu użytkownik jest przekierowywany na stronę oryginalną, która analizuje token dostępu z ciągu identyfikatora fragmentu.
  3. Strona używa tokena dostępu do wysyłania przykładowego żądania do interfejsu API.

    To żądanie do interfejsu API wywołuje metodę reports.query interfejsu YouTube Analytics API w celu pobrania liczby wyświetleń kanału YouTube autoryzowanego użytkownika.

  4. Jeśli żądanie zostanie wykonane, odpowiedź interfejsu API zostanie zarejestrowana w konsoli debugowania przeglądarki.

Dostęp do aplikacji możesz anulować na stronie Uprawnienia na swoim koncie Google. Aplikacja będzie oznaczona jako Wersja demonstracyjna OAuth 2.0 dla Dokumentów Google API.

Aby uruchomić ten kod lokalnie, ustaw wartości zmiennych YOUR_CLIENT_ID i YOUR_REDIRECT_URI, które odpowiadają Twoim danych logowania do autoryzacji. Zmienna YOUR_REDIRECT_URI powinna zawierać ten sam adres URL, pod którym wyświetla się strona. Wartość musi być dokładnie taka sama jak jeden z autoryzowanych identyfikatorów URI przekierowania dla klienta OAuth 2.0 skonfigurowanych w zadaniu API Console Credentials page. Jeśli ta wartość nie jest zgodna z autoryzowanym identyfikatorem URI, wystąpi błąd redirect_uri_mismatch. Twój projekt musi też włączyć odpowiedni interfejs API dla tego żądania.

<html><head></head><body>
<script>
  var YOUR_CLIENT_ID = 'REPLACE_THIS_VALUE';
  var YOUR_REDIRECT_URI = 'REPLACE_THIS_VALUE';
  var fragmentString = location.hash.substring(1);

  // Parse query string to see if page request is coming from OAuth 2.0 server.
  var params = {};
  var regex = /([^&=]+)=([^&]*)/g, m;
  while (m = regex.exec(fragmentString)) {
    params[decodeURIComponent(m[1])] = decodeURIComponent(m[2]);
  }
  if (Object.keys(params).length > 0) {
    localStorage.setItem('oauth2-test-params', JSON.stringify(params) );
    if (params['state'] && params['state'] == 'try_sample_request') {
      trySampleRequest();
    }
  }

  // If there's an access token, try an API request.
  // Otherwise, start OAuth 2.0 flow.
  function trySampleRequest() {
    var params = JSON.parse(localStorage.getItem('oauth2-test-params'));
    if (params && params['access_token']) {
      var xhr = new XMLHttpRequest();
      xhr.open('GET',
          'https://www.googleapis.com/youtube/analytics/v1/reports?ids=channel%3D%3DMINE&start-date=2016-05-01&end-date=2016-06-30&metrics=views&' +
          'access_token=' + params['access_token']);
      xhr.onreadystatechange = function (e) {
        if (xhr.readyState === 4 && xhr.status === 200) {
          console.log(xhr.response);
        } else if (xhr.readyState === 4 && xhr.status === 401) {
          // Token invalid, so prompt for user permission.
          oauth2SignIn();
        }
      };
      xhr.send(null);
    } else {
      oauth2SignIn();
    }
  }

  /*
   * Create form to request access token from Google's OAuth 2.0 server.
   */
  function oauth2SignIn() {
    // Google's OAuth 2.0 endpoint for requesting an access token
    var oauth2Endpoint = 'https://accounts.google.com/o/oauth2/v2/auth';

    // Create element to open OAuth 2.0 endpoint in new window.
    var form = document.createElement('form');
    form.setAttribute('method', 'GET'); // Send as a GET request.
    form.setAttribute('action', oauth2Endpoint);

    // Parameters to pass to OAuth 2.0 endpoint.
    var params = {'client_id': YOUR_CLIENT_ID,
                  'redirect_uri': YOUR_REDIRECT_URI,
                  'scope': 'https://www.googleapis.com/auth/yt-analytics.readonly',
                  'state': 'try_sample_request',
                  'include_granted_scopes': 'true',
                  'response_type': 'token'};

    // Add form parameters as hidden input values.
    for (var p in params) {
      var input = document.createElement('input');
      input.setAttribute('type', 'hidden');
      input.setAttribute('name', p);
      input.setAttribute('value', params[p]);
      form.appendChild(input);
    }

    // Add form to page and submit it to open the OAuth 2.0 endpoint.
    document.body.appendChild(form);
    form.submit();
  }
</script>

<button onclick="trySampleRequest();">Try sample request</button>
</body></html>

Reguły walidacji źródła JavaScript

Google stosuje poniższe reguły weryfikacji do źródeł JavaScript, aby pomóc programistom w ochronie aplikacji. Źródła JavaScript muszą być zgodne z tymi regułami. Definicję domeny, hosta i schematu znajdziesz poniżej w sekcji 3986 RFC 3986.

Reguły weryfikacji
Schemat

Źródła JavaScript muszą używać schematu HTTPS, a nie zwykłego HTTP. Identyfikatory URI hosta lokalnego (w tym identyfikatory URI adresów IP hosta lokalnego) są zwolnione z tej reguły.

Osoba prowadząca

Hosty nie mogą być nieprzetworzonymi adresami IP. Adresy IP hosta lokalnego są wykluczone z tej reguły.

Domena
  • Domeny najwyższego poziomu (domeny najwyższego poziomu) muszą znajdować się na liście domen publicznych.
  • Domeną hosta nie może być “googleusercontent.com”.
  • Źródło JavaScript nie może zawierać domen skracających adresy URL (np. goo.gl), chyba że domena jest własnością aplikacji.
  • Informacje o użytkowniku

    Źródło JavaScript nie może zawierać podkomponentu informacji o użytkowniku.

    Ścieżka

    Źródło JavaScript nie może zawierać komponentu ścieżki.

    Zapytanie

    Źródło JavaScript nie może zawierać komponentu zapytania.

    Fragment

    Źródło JavaScript nie może zawierać komponentu fragmentu.

    Znaki Źródło JavaScript nie może zawierać niektórych znaków, w tym:
    • Symbole wieloznaczne ('*')
    • Niedrukowalne znaki ASCII
    • Nieprawidłowe kodowanie procentowe (dowolne kodowanie procentowe inne niż kodowanie adresu URL ze znakiem procentu, po którym następują 2 cyfry szesnastkowe)
    • Znaki null (zakodowany znak NULL, np. %00, %C0%80)

    Autoryzacja przyrostowa

    W protokole OAuth 2.0 aplikacja żąda autoryzacji dostępu do zasobów identyfikowanych przez zakresy. Żądanie autoryzacji zasobów wtedy, gdy są potrzebne, jest uznawane za sprawdzoną dla wygody użytkowników. Aby umożliwić tę praktykę, serwer autoryzacji Google obsługuje autoryzację przyrostową. Ta funkcja pozwala żądać zakresów na bieżąco. Jeśli użytkownik przyzna uprawnienia do nowego zakresu, zwraca kod autoryzacji, który można wymienić na token zawierający wszystkie zakresy przyznane projektowi przez użytkownika.

    Załóżmy na przykład, że aplikacja pobiera raporty Statystyk YouTube, z których część zawiera raporty finansowe, które wymagają dostępu do dodatkowego zakresu, który nie jest potrzebny w przypadku innych raportów. W tym przypadku podczas logowania aplikacja może poprosić o dostęp tylko do zakresu https://www.googleapis.com/auth/yt-analytics.readonly. Jeśli jednak użytkownik spróbuje pobrać raport pieniężny, aplikacja może też poprosić o dostęp do zakresu https://www.googleapis.com/auth/yt-analytics-monetary.readonly.

    Do tokena dostępu uzyskanego dzięki autoryzacji przyrostowej mają zastosowanie te reguły:

    • Token może służyć do uzyskiwania dostępu do zasobów odpowiadających dowolnym z zakresów uwzględnionych w nowej, połączonej autoryzacji.
    • Gdy użyjesz tokena odświeżania połączonej autoryzacji w celu uzyskania tokena dostępu, będzie on reprezentuje połączoną autoryzację i może być użyty w przypadku dowolnej z wartości scope zawartych w odpowiedzi.
    • Połączona autoryzacja obejmuje wszystkie zakresy, które użytkownik przyznał projektowi interfejsu API, nawet jeśli żądania przyznano uprawnienia od różnych klientów. Jeśli na przykład użytkownik przyznał dostęp do jednego zakresu za pomocą klienta aplikacji na komputer, a następnie przyznał inny zakres tej samej aplikacji za pomocą klienta mobilnego, połączona autoryzacja obejmie oba zakresy.
    • Jeśli unieważnisz token reprezentujący połączoną autoryzację, dostęp do wszystkich zakresów tej autoryzacji w imieniu powiązanego użytkownika zostanie unieważniony jednocześnie.

    W przykładowym kodzie poniżej pokazano, jak dodać zakresy do istniejącego tokena dostępu. To podejście pozwala aplikacji uniknąć konieczności zarządzania wieloma tokenami dostępu.

    Punkty końcowe OAuth 2.0

    W tym przykładzie aplikacja wywołująca prosi o dostęp do pobrania danych ze Statystyk YouTube użytkownika w uzupełnieniu do innych uprawnień, które użytkownik już wcześniej przyznał aplikacji.

    Aby dodać zakresy do istniejącego tokena dostępu, umieść parametr include_granted_scopes w żądaniu wysyłanym do serwera OAuth 2.0 Google.

    Poniższy fragment kodu pokazuje, jak to zrobić. Fragment kodu zakłada, że masz zapisane w pamięci lokalnej przeglądarki zakresy, dla których Twój token dostępu jest prawidłowy. (Kod pełnego przykładu zawiera listę zakresów, dla których token dostępu jest prawidłowy, ustawiając właściwość oauth2-test-params.scope w pamięci lokalnej przeglądarki).

    Fragment kodu porównuje zakresy, dla których token dostępu jest prawidłowy, z zakresem, którego chcesz użyć w przypadku konkretnego zapytania. Jeśli token dostępu nie obejmuje tego zakresu, rozpocznie się proces OAuth 2.0. Tutaj funkcja oauth2SignIn jest taka sama jak ta podana w kroku 2 (została przedstawiona w dalszej części pełnego przykładu).

    var SCOPE = 'https://www.googleapis.com/auth/yt-analytics.readonly';
    var params = JSON.parse(localStorage.getItem('oauth2-test-params'));
    
    var current_scope_granted = false;
    if (params.hasOwnProperty('scope')) {
      var scopes = params['scope'].split(' ');
      for (var s = 0; s < scopes.length; s++) {
        if (SCOPE == scopes[s]) {
          current_scope_granted = true;
        }
      }
    }
    
    if (!current_scope_granted) {
      oauth2SignIn(); // This function is defined elsewhere in this document.
    } else {
      // Since you already have access, you can proceed with the API request.
    }

    Unieważnianie tokena

    W niektórych przypadkach użytkownik może zechcieć anulować dostęp przyznany aplikacji. Użytkownik może anulować dostęp w Ustawieniach konta. Więcej informacji znajdziesz w sekcji dotyczącej usuwania dostępu witryny lub aplikacji w dokumencie „Witryny i aplikacje innych firm, które mają dostęp do Twojego konta”.

    Aplikacja może też automatycznie anulować przyznany jej dostęp. Automatyczne unieważnianie jest ważne w przypadkach, gdy użytkownik anuluje subskrypcję, usunie aplikację lub znacząco zmieniły się zasoby interfejsu API wymagane przez aplikację. Innymi słowy, część procesu usuwania może obejmować żądanie do interfejsu API, aby mieć pewność, że uprawnienia przyznane wcześniej aplikacji zostały usunięte.

    Punkty końcowe OAuth 2.0

    Aby programowo unieważnić token, aplikacja wysyła żądanie do https://oauth2.googleapis.com/revoke i uwzględnia ten token jako parametr:

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

    Token może być tokenem dostępu lub tokenem odświeżania. Jeśli token jest tokenem dostępu i ma odpowiedni token odświeżania, token odświeżania również zostanie unieważniony.

    Jeśli odwołanie zostanie przetworzone, kod stanu HTTP odpowiedzi to 200. W przypadku błędu zwracany jest kod stanu HTTP 400 wraz z kodem błędu.

    Poniższy fragment kodu JavaScript pokazuje, jak unieważnić token w JavaScript bez używania biblioteki klienta interfejsów API Google do obsługi JavaScriptu. Ponieważ punkt końcowy Google OAuth 2.0 do unieważniania tokenów nie obsługuje udostępniania zasobów między domenami (CORS), kod tworzy formularz i przesyła go do punktu końcowego, zamiast używać metody XMLHttpRequest() do opublikowania żądania.

    function revokeAccess(accessToken) {
      // Google's OAuth 2.0 endpoint for revoking access tokens.
      var revokeTokenEndpoint = 'https://oauth2.googleapis.com/revoke';
    
      // Create <form> element to use to POST data to the OAuth 2.0 endpoint.
      var form = document.createElement('form');
      form.setAttribute('method', 'post');
      form.setAttribute('action', revokeTokenEndpoint);
    
      // Add access token to the form so it is set as value of 'token' parameter.
      // This corresponds to the sample curl request, where the URL is:
      //      https://oauth2.googleapis.com/revoke?token={token}
      var tokenField = document.createElement('input');
      tokenField.setAttribute('type', 'hidden');
      tokenField.setAttribute('name', 'token');
      tokenField.setAttribute('value', accessToken);
      form.appendChild(tokenField);
    
      // Add form to page and submit it to actually revoke the token.
      document.body.appendChild(form);
      form.submit();
    }