Bezpośrednie prośby

Zachęcamy do korzystania z bibliotek klienta i przykładowych kodów podczas wdrażania. Jeśli jednak integracja z interfejsem API ma specjalne wymagania, np. używa nieobsługiwanego języka, możesz wysyłać bezpośrednie żądania w sposób opisany poniżej.

Styl połączeń

REST to styl architektury oprogramowania, który zapewnia wygodne i spójne podejście do wysyłania żądań dotyczących danych i ich modyfikowania.

REST to skrót od „Representational State Transfer”. W kontekście interfejsów API Google oznacza to używanie czasowników HTTP do pobierania i modyfikowania reprezentacji danych przechowywanych przez Google.

W systemie RESTful zasoby są przechowywane w magazynie danych. Klient wysyła żądanie, aby serwer wykonał określone działanie (np. utworzył, pobrał, zaktualizował lub usunął zasób), a serwer wykonuje to działanie i wysyła odpowiedź, często w formie reprezentacji określonego zasobu.

W interfejsach API REST Google klient określa działanie za pomocą czasownika HTTP, takiego jak POST, GET, PUT lub DELETE. Określa zasób za pomocą unikalnego globalnie identyfikatora URI w tej postaci:

https://www.googleapis.com/apiName/apiVersion/resourcePath?parameters

Ponieważ wszystkie zasoby interfejsu API mają unikalne identyfikatory URI dostępne przez HTTP, REST umożliwia buforowanie danych i jest zoptymalizowany pod kątem współpracy z rozproszoną infrastrukturą internetu.

W dokumentacji standardów HTTP 1.1 znajdziesz definicje metod, w tym specyfikacje metod GET, POST, PUT i DELETE.

REST w interfejsie AdSense Management API

Obsługiwane operacje są bezpośrednio powiązane z czasownikami REST HTTP.

Identyfikatory URI interfejsu AdSense Management API mają te formaty:

https://adsense.googleapis.com/v2/resourceID?parameters

gdzie resourceID to identyfikator klienta reklamowego, jednostki reklamowej, kanału URL, kanału niestandardowego lub kolekcji raportów, a parameters to parametry, które mają być zastosowane w zapytaniu.

Format resourceID rozszerzeń ścieżki umożliwia identyfikację zasobu, na którym obecnie pracujesz, np.:

https://adsense.googleapis.com/v2/accounts/account_id/adclients
https://adsense.googleapis.com/v2/accounts/account_id/adclients/adClientId
https://adsense.googleapis.com/v2/accounts/account_id/adclients/adClientId/adunits
https://adsense.googleapis.com/v2/accounts/account_id/adclients/adClientId/adunits/adUnitId
https://adsense.googleapis.com/v2/accounts/account_id/adclients/adClientId/urlchannels
...

Pełny zestaw identyfikatorów URI używanych w przypadku każdej obsługiwanej operacji w interfejsie API znajdziesz w dokumencie Dokumentacja interfejsu AdSense Management API.

Oto kilka przykładów, jak to działa w interfejsie AdSense Management API.

Wyświetlanie listy klientów reklam:

GET https://adsense.googleapis.com/v2/accounts/account_id/adclients/

Wyświetl listę jednostek reklamowych na koncie klienta reklamowego ca-pub-1234567890123456:

GET https://adsense.googleapis.com/v2/accounts/account_id/adclients/ca-pub-1234567890123456/adunits

Format danych

JSON (JavaScript Object Notation) to popularny, niezależny od języka format danych, który zapewnia prostą tekstową reprezentację dowolnych struktur danych. Więcej informacji znajdziesz na stronie json.org.

Autoryzowanie zapytań

Pamiętaj, że AdSense nie obsługuje kont usług. Zamiast nich musisz używać przepływu zainstalowanej aplikacji.

Każde żądanie wysyłane przez aplikację do interfejsu AdSense Management API musi zawierać token autoryzacji. Token stanowi też dla Google identyfikator aplikacji.

Informacje o protokołach autoryzacji

Twoja aplikacja musi autoryzować żądania za pomocą protokołu OAuth 2.0. Inne protokoły nie są obsługiwane. Jeśli aplikacja używa funkcji Zaloguj się przez Google, niektórymi aspektami autoryzacji nie musisz się zajmować.

Autoryzowanie żądań za pomocą protokołu OAuth 2.0

Wszystkie żądania wysyłane do interfejsu AdSense Management API muszą być autoryzowane przez uwierzytelnionego użytkownika.

Ten proces jest ułatwiony dzięki identyfikatorowi klienta OAuth.

Pobieranie identyfikatora klienta OAuth

Możesz też utworzyć go na stronie Dane logowania.

Szczegóły procesu autoryzacji z użyciem protokołu OAuth 2.0 różnią się nieznacznie w zależności od rodzaju projektowanej aplikacji. Do większości typów aplikacji ma zastosowanie ten ogólny proces:

  1. Gdy Twoja aplikacja potrzebuje dostępu do danych użytkownika, prosi Google o konkretny zakres dostępu.
  2. Google wyświetla użytkownikowi ekran zgody z prośbą o autoryzowanie dostępu aplikacji do niektórych danych.
  3. Jeśli użytkownik wyrazi zgodę, Google przekazuje Twojej aplikacji ważny przez krótki czas token dostępu.
  4. Aplikacja żąda danych użytkownika i dołącza do żądania token dostępu.
  5. Jeśli Google uzna, że żądanie i token są prawidłowe, przesyła dane, o które prosisz.

Niektóre procesy obejmują dodatkowe kroki, takie jak wykorzystanie tokenów odświeżania do uzyskania nowych tokenów dostępu. Szczegółowe informacje o procesach obowiązujących w przypadku różnych typów aplikacji znajdziesz w dokumencie Google na temat protokołu OAuth 2.0.

Oto zakres danych protokołu OAuth 2.0 dla interfejsu AdSense Management API:

Zakres Znaczenie
https://www.googleapis.com/auth/adsense Uprawnienia do odczytu i zapisu danych AdSense.
https://www.googleapis.com/auth/adsense.readonly Dostęp tylko do odczytu danych AdSense.

Aby poprosić o dostęp przy użyciu protokołu OAuth 2.0, aplikacja potrzebuje danych z zakresu oraz informacji przekazywanych przez Google po zarejestrowaniu aplikacji (takich jak identyfikator klienta i tajny klucz klienta).

Wskazówka: biblioteki klienta interfejsów API Google mogą wykonać niektóre procesy autoryzacji za Ciebie. Są dostępne dla różnych języków programowania. Więcej szczegółów znajdziesz na stronie z bibliotekami i próbkami.

Tworzenie żądania

Ostatnim krokiem jest wysłanie żądania do interfejsu API. Szczegółowe informacje znajdziesz w dokumentacji.