Przewodnik wprowadzający do interfejsu Google Ads API

W tym przewodniku znajdziesz szczegółowe informacje o całym procesie wdrażania, uwierzytelniania i wykonywania pierwszego wywołania interfejsu Google Ads API.

1. Wymagania wstępne i hierarchia kont

Zanim zaczniesz korzystać z interfejsu Google Ads API, musisz zrozumieć hierarchię kont i mieć prawidłową strukturę konta najwyższego poziomu.

  • Konto menedżera (MCK): konto menedżera Google Ads (dawniej Moje Centrum Klienta) to główne konto służące do wyświetlania i zarządzania wieloma kontami klientów. Aby ubiegać się o token programisty interfejsu Google Ads API, musisz mieć konto menedżera.
  • Konto klienta: standardowe konto, na którym tworzone są kampanie, grupy reklam i reklamy oraz konfigurowane są rozliczenia.

Działanie: jeśli nie masz konta menedżera, utwórz je w Google Ads na stronie Konta menedżera.

2. Uzyskiwanie tokena programisty

Token programisty jednoznacznie identyfikuje Twoją aplikację w interfejsie Google Ads API i określa poziom dostępu do limitu wywołań.

Etapy do przejścia

  1. Zaloguj się na konto menedżera Google Ads.
  2. Otwórz Narzędzia i ustawienia > Konfiguracja > Centrum API (lub Administracja > Centrum API).
  3. Wypełnij formularz z informacjami o deweloperze i zaakceptuj Warunki korzystania z interfejsu API.
  4. Prześlij zgłoszenie.

Poziomy dostępu

  • Oczekujące na zatwierdzenie: nowo utworzone tokeny od razu otrzymują stan „Oczekujące”. Możesz użyć tokena oczekującego na zatwierdzenie, aby od razu połączyć się z kontami testowymi , ale nie będzie on działać na kontach produkcyjnych.
  • Podstawowy dostęp: po zatwierdzeniu umożliwia wykonywanie do 15 tys. operacji API dziennie.
  • Standardowy dostęp: nieograniczona liczba operacji API dziennie w przypadku aplikacji, które spełniają wymagania dotyczące Wymaganej minimalnej funkcjonalności (WMF).

3. Konfigurowanie kont testowych

Tworzenie i testowanie na kontach produkcyjnych wiąże się z ryzykiem niechcianych wydatków na reklamę i modyfikacji kampanii. Zdecydowanie zalecamy, aby wszystkie aktywne prace deweloperskie wykonywać na kontach testowych.

Tworzenie testowego konta menedżera

  1. Otwórz stronę tworzenia konta menedżera Google Ads.
  2. Zaloguj się za pomocą konta Google, które nie jest jeszcze połączone z Twoim produkcyjnym kontem menedżera Google Ads.
  3. Wpisz opisową nazwę konta (np. MyCompany Test MCC).
  4. Jako główne zastosowanie wybierz Zarządzanie kontami innych użytkowników.
  5. Wybierz kraj rozliczenia, strefę czasową i walutę. Kliknij Zapisz i kontynuuj.

Tworzenie testowego konta klienta

Po utworzeniu testowego konta menedżera musisz utworzyć co najmniej 1 podrzędne konto klienta, aby móc uruchamiać kampanie testowe.

  1. Zaloguj się na nowo utworzone testowe konto menedżera.
  2. W menu nawigacyjnym po lewej stronie kliknij Konta, a następnie wybierz Ustawienia subkonta (lub Skuteczność).
  3. Kliknij niebieski przycisk + (plus) i wybierz Utwórz nowe konto.
  4. Wybierz Konto Google Ads.
  5. Wpisz nazwę konta (np. Test Client Account A).
  6. Wybierz strefę czasową i walutę, a potem kliknij Zapisz i kontynuuj.
  7. Zapisz 10-cyfrowy identyfikator klienta (np. 1234567890 bez łączników) tego nowego konta klienta.

Ważne zasady dotyczące kont testowych

  • Używanie tokena programisty: nie wysyłaj prośby o token programisty z testowego konta menedżera. Zawsze używaj oczekującego na zatwierdzenie lub zatwierdzonego tokena programisty z produkcyjnego konta menedżera.
  • Rozliczenia: konta testowe nie wyświetlają prawdziwych reklam, więc nie musisz podawać prawdziwych informacji rozliczeniowych.

4. Konfigurowanie projektu Google Cloud

Wszystkie żądania wysyłane do interfejsu API muszą być uwierzytelniane za pomocą projektu w chmurze Google Cloud z włączonym interfejsem Google Ads API.

Instrukcje włączania interfejsu API

  1. Otwórz konsolę Google Cloud.
  2. Utwórz nowy projekt lub wybierz już istniejący.
  3. Wybierz Interfejsy API i usługi > Biblioteka.
  4. Wyszukaj interfejs Google Ads API i kliknij Włącz.

Ceny i płatności

  • Brak opłat za interfejs API: utworzenie projektu w chmurze Google Cloud, włączenie interfejsu Google Ads API i wygenerowanie danych logowania OAuth 2.0 jest bezpłatne. Google nie pobiera żadnych opłat za wywoływanie ani korzystanie z interfejsu Google Ads API.
  • Inne zasoby w chmurze: opłaty za Google Cloud będą naliczane tylko wtedy, gdy aktywnie korzystasz z innych płatnych usług Google Cloud (takich jak Compute Engine, Cloud Run czy BigQuery) poza limitami poziomu bezpłatnego, aby hostować aplikację lub przechowywać dane reklamowe.

5. Konfigurowanie uwierzytelniania OAuth 2.0

Interfejs Google Ads API używa protokołu OAuth 2.0 do uwierzytelniania i autoryzowania żądań.

Instrukcje dotyczące przepływu aplikacji na komputery

  1. W projekcie Google Cloud otwórz Interfejsy API i usługi > Ekran zgody OAuth i skonfiguruj ekran zgody. Gdy aplikacja jest w stanie testowania, dodaj swój adres e-mail do sekcji Użytkownicy testowi , aby zapobiec błędom dostępu podczas autoryzacji.
  2. Otwórz Interfejsy API i usługi > Dane logowania.
  3. Kliknij Utwórz dane logowania > Identyfikator klienta OAuth.
  4. Jako typ aplikacji wybierz Aplikacja na komputery.
  5. Kliknij Utwórz, a następnie pobierz plik danych logowania OAuth jako client_secret.json (lub skopiuj Client ID i Client Secret).

Generowanie tokena odświeżania

Gdy masz już identyfikator i tajny klucz klienta, musisz wygenerować token odświeżania. Możesz to zrobić za pomocą OAuth 2.0 Playground Google lub skryptu biblioteki klienta.

Metoda A. Użyj OAuth 2.0 Playground Google

  1. Otwórz OAuth 2.0 Playground Google.
  2. W prawym górnym rogu kliknij ikonę koła zębatego (konfiguracja OAuth 2.0).
  3. Zaznacz pole Użyj własnych danych logowania OAuth.
  4. Wpisz Client ID i Client Secret OAuth2, a potem kliknij Zamknij.
  5. W kroku 1 (Wybierz i autoryzuj interfejsy API) po lewej stronie wpisz zakres interfejsu Google Ads API w polu „Wpisz własne zakresy”: https://www.googleapis.com/auth/adwords
  6. Kliknij Autoryzuj interfejsy API. Po wyświetleniu monitu zaloguj się na konto Google, które ma dostęp do Twojego konta menedżera Google Ads (lub konta testowego).
  7. Na ekranie zgody kliknij Dalej.
  8. W kroku 2 (Kod autoryzacji wymiany dla tokenów) kliknij niebieski przycisk Kod autoryzacji wymiany dla tokenów.
  9. W panelu odpowiedzi zostaną wyświetlone Refresh token i Access token. Skopiuj i zapisz Refresh token.

Metoda B. Użyj skryptu biblioteki klienta (przykład w Pythonie)

Oficjalna biblioteka klienta w Pythonie zawiera wbudowany skrypt pomocniczy do generowania danych logowania. Możesz też pobrać plik client_secret.json z konsoli Google Cloud i uruchomić ten samodzielny skrypt w Pythonie:

  1. Zainstaluj wymaganą bibliotekę OAuth:
pip install google-auth-oauthlib
  1. W tym samym katalogu co client_secret.json utwórz skrypt o nazwie generate_refresh_token.py i uruchom go:
from google_auth_oauthlib.flow import InstalledAppFlow

CLIENT_SECRETS_FILE = "client_secret.json"
SCOPES = ["https://www.googleapis.com/auth/adwords"]

def main():
    flow = InstalledAppFlow.from_client_secrets_file(
        CLIENT_SECRETS_FILE, SCOPES
    )
    credentials = flow.run_local_server(port=0)
    
    print("\nAuthorization Successful!\n")
    print(f"Refresh Token: {credentials.refresh_token}")

if __name__ == "__main__":
    main()

6. Konfigurowanie biblioteki klienta i danych logowania

Google udostępnia oficjalnie obsługiwane biblioteki klienta, które obsługują uwierzytelnianie, serializację i komunikację z punktami końcowymi gRPC.

Obsługiwane języki

  • Python: pip install google-ads
  • Java: dostępna przez Maven lub Gradle
  • PHP: composer require googleads/google-ads-php
  • .NET: Install-Package Google.Ads.GoogleAds
  • Ruby: gem install google-ads-googleads
  • Perl: cpanm Google::Ads::GoogleAds::Client

Plik konfiguracyjny (google-ads.yaml)

Utwórz plik konfiguracyjny zawierający Twoje dane logowania. Domyślnie metoda inicjowania biblioteki klienta (np. GoogleAdsClient.load_from_storage()) automatycznie wyszuka plik google-ads.yaml w 2 lokalizacjach:

  1. Bieżący katalog roboczy , z którego uruchamiany jest skrypt.
  2. Katalog domowy użytkownika (~ w systemie Linux/macOS lub %HOMEPATH% w systemie Windows).

Jeśli przechowujesz plik w niestandardowej lokalizacji, możesz jawnie przekazać ścieżkę do metody inicjowania (np. load_from_storage("path/to/google-ads.yaml")).

developer_token: "INSERT_YOUR_DEVELOPER_TOKEN_HERE"
client_id: "INSERT_YOUR_OAUTH2_CLIENT_ID_HERE"
client_secret: "INSERT_YOUR_OAUTH2_CLIENT_SECRET_HERE"
refresh_token: "INSERT_YOUR_OAUTH2_REFRESH_TOKEN_HERE"
login_customer_id: "INSERT_YOUR_MANAGER_ACCOUNT_ID_HERE"

7. Wykonywanie pierwszego wywołania interfejsu API

Aby zweryfikować konfigurację wdrażania, uruchom skrypt szybkiego startu, aby pobrać istniejące kampanie z konta testowego.

Przykładowy skrypt w Pythonie (quickstart.py)

import sys
from google.ads.googleads.client import GoogleAdsClient
from google.ads.googleads.errors import GoogleAdsException

def main(client, customer_id):
    ga_service = client.get_service("GoogleAdsService")
    query = """
        SELECT
          campaign.id,
          campaign.name
        FROM campaign
        ORDER BY campaign.id
    """
    
    # Issues a search request
    stream = ga_service.search_stream(customer_id=customer_id, query=query)
    for batch in stream:
        for row in batch.results:
            print(
                f"Campaign with ID {row.campaign.id} and name "
                f"'{row.campaign.name}' was found."
            )

if __name__ == "__main__":
    # Initialize client from google-ads.yaml
    # By default, load_from_storage() searches for 'google-ads.yaml' in the
    # current working directory or the user's home directory (~). You can
    # also pass an explicit path: load_from_storage("path/to/google-ads.yaml")
    try:
        googleads_client = GoogleAdsClient.load_from_storage()
        # Replace with your test client account ID (without hyphens) from
        # Section 3, NOT your manager account ID (which belongs in
        # google-ads.yaml).
        test_customer_id = "1234567890" 
        main(googleads_client, test_customer_id)
    except GoogleAdsException as ex:
        print(
            f"Request failed with status {ex.error.code().name} and "
            f"includes the following errors:"
        )
        for error in ex.failure.errors:
            print(f"\tError with message '{error.message}'.")
            if error.location:
                for field_path_element in error.location.field_path_elements:
                    print(f"\t\tOn field: {field_path_element.field_name}")
        sys.exit(1)

8. Sprawdzone metody i zasoby

  • Logowanie: włącz szczegółowe logowanie w bibliotece klienta, aby rejestrować identyfikatory żądań i odpowiedzi (request-id), które są niezbędne podczas kontaktowania się z zespołem pomocy Google.
  • Obsługa błędów: zaimplementuj niezawodną obsługę błędów GoogleAdsException, w szczególności zarządzanie limitami szybkości (RESOURCE_TEMPORARILY_EXHAUSTED).
  • Oficjalna dokumentacja: dokumentacja dla deweloperów interfejsu Google Ads API
  • Biblioteki klienta i przykłady kodu: repozytoria Google Ads na GitHubie
Wstecz
Wprowadzenie
Dalej
Krótkie wprowadzenie