Zachęcamy do korzystania z bibliotek klienta i przykładów do implementacji. Jeśli jednak integracja z interfejsem API ma specjalne potrzeby, na przykład używasz nieobsługiwanego języka, możesz wysyłać żądania bezpośrednie w sposób opisany poniżej.
Styl połączeń
REST to styl architektury oprogramowania zapewniający wygodne i spójne podejście do żądania i modyfikowania danych.
Termin REST to skrót od „Representational State Transfer”. W kontekście interfejsów API Google odnosi się do korzystania z czasowników HTTP do pobierania i modyfikowania reprezentacji danych przechowywanych przez Google.
W systemie REST zasoby są przechowywane w magazynie danych. Klient wysyła żądanie, aby serwer przystąpił do realizacji konkretnego działania (na przykład utworzenia, pobrania, zaktualizowania lub usunięcia zasobu), serwer wykonuje działanie i wysyła odpowiedź, często w formie reprezentacji określonego zasobu.
W interfejsach API Google typu REST klient określa działanie przy użyciu czasownika HTTP, takiego jak POST
, GET
, PUT
czy DELETE
. Zasób określa go za pomocą unikalnego identyfikatora URI, który ma postać:
https://www.googleapis.com/apiName/apiVersion/resourcePath?parameters
Wszystkie zasoby interfejsu API mają unikalne identyfikatory URI dostępne przez HTTP, dlatego REST umożliwia buforowanie danych i jest zoptymalizowany pod kątem współpracy z rozproszoną infrastrukturą sieci.
Definicje metod można znaleźć w dokumentacji standardów HTTP 1.1. Obejmują one specyfikacje GET
, POST
, PUT
i DELETE
.
REST w interfejsie AdSense Management API
Obsługiwane operacje są mapowane bezpośrednio na czasowniki HTTP REST, zgodnie z opisem w artykule Operacje interfejsu API do zarządzania AdSense.
Odpowiedni format identyfikatorów URI do zarządzania interfejsem AdSense Management API to:
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 stosowane do zapytania.
Format rozszerzeń ścieżki resourceID
pozwala Ci zidentyfikować zasób, w którym pracujesz. Na przykład:
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 ...
Podsumowanie pełnych identyfikatorów URI używanych w przypadku każdej obsługiwanej operacji w interfejsie API znajdziesz w dokumencie AdSense Management API.
Oto kilka przykładów, jak to działa w interfejsie AdSense Management API.
Lista klientów reklamowych:
GET https://adsense.googleapis.com/v2/accounts/account_id/adclients/
Wyświetl listę jednostek reklamowych w pliku ca-pub-1234567890123456 klienta reklamowego:
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 przedstawia proste struktury danych w formie tekstowej. Więcej informacji znajdziesz na stronie json.org.
Autoryzowanie zapytań
Pamiętaj, że AdSense nie obsługuje kont usługi. Zamiast tego musisz użyć procesu Zainstalowana aplikacja.
Każde żądanie wysyłane przez aplikację do interfejsu API do zarządzania AdSense 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 użytkownika.
Można to zrobić za pomocą identyfikatora klienta OAuth.
Uzyskiwanie identyfikatora klienta OAuthMożesz też je utworzyć 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:
- Gdy Twoja aplikacja potrzebuje dostępu do danych użytkownika, prosi Google o konkretny zakres dostępu.
- Google wyświetla użytkownikowi ekran zgody z prośbą o autoryzowanie dostępu aplikacji do niektórych danych.
- Jeśli użytkownik wyrazi zgodę, Google przekazuje Twojej aplikacji ważny przez krótki czas token dostępu.
- Aplikacja żąda danych użytkownika i dołącza do żądania token dostępu.
- 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.
Informacje o zakresie protokołu OAuth 2.0 dla interfejsu AdSense Management API:
Zakres | Znaczenie |
---|---|
https://www.googleapis.com/auth/adsense |
Uprawnienia do zapisu i odczytu danych AdSense. |
https://www.googleapis.com/auth/adsense.readonly |
Dostęp tylko do odczytu do 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.
Przesyłanie prośby
Ostatnim krokiem jest utworzenie żądania do interfejsu API. Więcej informacji na ten temat znajdziesz w dokumentacji referencyjnej.