Ten przewodnik szybkiego startu pomoże Ci wykonać pierwsze wywołanie interfejsu Google Ads API.
Kluczowe pojęcia
- Projekt Google Cloud: projekt Google Cloud stanowi podstawę do tworzenia, włączania i używania wszystkich usług Google, w tym do zarządzania interfejsami API i danymi logowania do interfejsu API OAuth 2.0. Możesz go utworzyć w konsoli Google Cloud.
- Poziom dostępu do interfejsu API: poziom dostępu do interfejsu API w Twoim projekcie Google Cloud określa liczbę wywołań interfejsu API, które możesz wykonywać dziennie, oraz środowiska, do których możesz wysyłać wywołania interfejsu API. Poziom dostępu do interfejsu API Twojego projektu jest podany na stronie Przegląd interfejsu Google Ads API.
- Konto menedżera Google Ads: konto menedżera Google Ads służy do zarządzania innymi kontami Google Ads, które mogą być zbiorem kont klientów Google Ads lub innych kont menedżera Google Ads.
- Konto klienta Google Ads: konto Google Ads używane do wyświetlania reklam, na które chcesz kierować wywołania interfejsu API.
- Identyfikator klienta klienta: 10-cyfrowy numer identyfikujący konto klienta Google Ads. Jeśli ten identyfikator został skopiowany z interfejsu Google Ads, usuń myślniki.
- OAuth 2.0: OAuth 2.0 to standardowy protokół autoryzacji używany przez wszystkie interfejsy API Google. Aby generować dane logowania OAuth 2.0 do wywoływania interfejsu API, potrzebujesz konta usługi i klucza.
- Konto usługi: specjalny rodzaj konta Google, które należy do aplikacji, a nie do użytkownika. Służy do uwierzytelniania aplikacji w interfejsie Google Ads API. Aby uzyskać konto usługi, musisz mieć projekt Google Cloud.
- Klucz konta usługi: plik JSON z danymi logowania aplikacji, który zawiera klucz prywatny konta usługi. Służy do generowania danych logowania OAuth 2.0 na potrzeby uwierzytelniania konta usługi podczas wywoływania interfejsu Google Ads API. Aby uzyskać klucz konta usługi, musisz mieć konto usługi.
Wymagania wstępne
Aby wykonać wywołanie Google Ads API, wykonaj te czynności.
Konfigurowanie projektu w chmurze na potrzeby dostępu do interfejsu Google Ads API
Projekt Google Cloud służy do zarządzania interfejsami API Google i danymi logowania do interfejsu OAuth 2.0 API. Istniejące projekty Google Cloud możesz znaleźć lub utworzyć nowy, otwierając konsolę Google Cloud.
Zacznij od włączenia interfejsu Google Ads API w projekcie:
Włączanie interfejsu Google Ads API
Następnie otwórz stronę z omówieniem interfejsu Google Ads API. Na stronie wyświetlany jest bieżący poziom dostępu do interfejsu API. Jeśli Twój obecny poziom dostępu do interfejsu API to Test, rozwiń sekcję Podnieś poziom dostępu. Postępuj zgodnie z instrukcjami, aby poprosić o poziom dostępu Explorer.
Po przesłaniu zgłoszenia Google automatycznie je sprawdzi i w większości przypadków zmieni status na Eksplorator. Jeśli nie masz dostępu do wersji Explorer, nie martw się. W tym przewodniku znajdziesz odpowiednie instrukcje dotyczące konfigurowania konta klienta Google Ads.
Tworzenie konta usługi
Aby wywoływać interfejs API, musisz mieć konto usługi i klucz konta usługi. Jeśli korzystasz już z innego interfejsu API Google i masz utworzone konto usługi OAuth 2.0 oraz klucz, możesz pominąć ten krok i ponownie użyć dotychczasowych danych logowania.
Jak utworzyć konto usługi i klucz
- W konsoli Google Cloud otwórz Menu > Uprawnienia i administracja > Konta usługi.
- Wybierz konto usługi.
- Kliknij Klucze > Dodaj klucz > Utwórz nowy klucz.
- Wybierz JSON, a potem kliknij Utwórz.
Nowa para kluczy publicznych/prywatnych zostanie wygenerowana i pobrana na Twoje urządzenie jako nowy plik. Zapisz pobrany plik JSON jako
credentials.jsonw katalogu roboczym. Ten plik jest jedyną kopią tego klucza. Nie przesyłaj plikucredentials.jsondo systemu kontroli wersji (np. nie dodawaj go do pliku.gitignore). - Kliknij Zamknij.
Konfigurowanie konta klienta Google Ads
Zacznij od określenia konta Google Ads, na którym wykonujesz wywołania interfejsu API. Rodzaj konta, do którego możesz wywoływać interfejs API, zależy od poziomu dostępu do interfejsu API w Twoim projekcie Google Cloud. Poziom dostępu do interfejsu API znajdziesz na stronie przeglądu interfejsu Google Ads API.
Poziomy dostępu Eksplorator, Podstawowy i Standardowy
Możesz wykonywać połączenia z kontem produkcyjnym Google Ads. W razie potrzeby możesz jednak utworzyć testowe konto Google Ads, postępując zgodnie z instrukcjami na karcie Dostęp testowy.
Testowanie dostępu
Projektu Google Cloud nie można używać do wywoływania interfejsu API na koncie produkcyjnym Google Ads. Wywołania interfejsu API możesz wykonywać tylko na kontach testowych Google Ads.
Jak utworzyć konto testowe Google Ads
Poniższe instrukcje pozwolą Ci utworzyć testowe konto menedżera Google Ads i testowe konto reklamodawcy Google Ads.
Kliknij niebieski przycisk, aby utworzyć testowe konto menedżera Google Ads. Jeśli pojawi się taka prośba, zaloguj się na konto Google, które nie jest połączone z Twoim produkcyjnym kontem menedżera Google Ads. Jeśli nie masz konta, kliknij przycisk Utwórz konto na tej stronie, aby utworzyć nowe konto Google.
- Na koncie menedżera testowego Google Ads utwórz testowe konto klienta Google Ads: kliknij Konta > > Utwórz nowe konto i wypełnij formularz. Wszystkie konta Google Ads utworzone z poziomu testowego konta menedżera Google Ads są automatycznie kontami testowymi Google Ads.
- Opcjonalnie utwórz kilka kampanii na koncie testowym klienta Google Ads na stronie Google Ads.
Aby wywołać interfejs API klienta Google Ads, musisz przyznać kontu usługi dostęp do konta klienta Google Ads i odpowiednie uprawnienia. Aby to zrobić, musisz mieć dostęp administracyjny do konta klienta.
Jak przyznać kontu usługi dostęp do konta Google Ads
- Zacznij od zalogowania się na konto Google Ads jako administrator.
- Kliknij Administracja > Dostęp i bezpieczeństwo.
- Kliknij przycisk na karcie Użytkownicy.
- Wpisz adres e-mail konta usługi w polu Adres e-mail.
Wybierz odpowiedni poziom dostępu do konta i kliknij przycisk Dodaj konto. Pamiętaj, że poziom dostępu do e-maili nie jest obsługiwany w przypadku kont usługi.
- Konto usługi otrzymuje dostęp.
- [Opcjonalnie] Podczas początkowej konfiguracji nie możesz przyznać dostępu administratora do konta usługi. Jeśli wywołania interfejsu API wymagają dostępu administratora, możesz go uaktualnić w ten sposób.
- Kliknij strzałkę menu obok poziomu dostępu konta usługi w kolumnie Poziom dostępu.
- Z menu wybierz Administrator.
Pobieranie narzędzi i bibliotek klienta
Możesz pobrać bibliotekę klienta lub klienta HTTP w zależności od tego, jak chcesz wywoływać interfejs API.
Korzystanie z biblioteki klienta
Pobierz i zainstaluj wybraną bibliotekę klienta.
Używanie klienta HTTP (REST)
curl
Pobierz i zainstaluj curl, narzędzie wiersza poleceń do przesyłania danych za pomocą adresu URL.
Interfejs wiersza poleceń Google Cloud
Aby zainstalować gcloud CLI, postępuj zgodnie z przewodnikiem instalacji Google Cloud CLI.
Instrukcje w pozostałej części tego przewodnika zostały sprawdzone pod kątem działania z tą wersją narzędzia gcloud i mogą nie działać w przypadku wcześniejszych wersji ze względu na różnice w zachowaniu aplikacji lub opcjach wiersza poleceń.
:~$ gcloud version
Google Cloud SDK 492.0.0
alpha 2024.09.06
beta 2024.09.06
bq 2.1.8
bundled-python3-unix 3.11.9
core 2024.09.06
enterprise-certificate-proxy 0.3.2
gcloud-crc32c 1.0.0
gsutil 5.30Wywoływanie interfejsu API
Aby uzyskać instrukcje dotyczące wykonywania wywołań interfejsu API, wybierz klienta:
Java
Artefakty biblioteki klienta są publikowane w repozytorium Maven Central.
Aby zarządzać wersjami zależności i zapobiegać konfliktom, zapoznaj się z przewodnikiem po liście materiałów interfejsu Google Ads API.
Jeśli nie używasz BOM, dodaj bibliotekę klienta bezpośrednio do projektu, korzystając z jednego z tych narzędzi do kompilacji:
Maven: dodaj do pliku pom.xml tę zależność:
<dependency>
<groupId>com.google.api-ads</groupId>
<artifactId>google-ads</artifactId>
<version>47.0.0</version>
</dependency>
Gradle dodaj tę zależność do pliku build.gradle:
implementation 'com.google.api-ads:google-ads:47.0.0'
W katalogu głównym (~/ads.properties w systemach Linux i macOS lub %USERPROFILE%\ads.properties w systemie Windows) utwórz plik ads.properties z tą zawartością:
api.googleads.serviceAccountSecretsPath=JSON_KEY_FILE_PATH
api.googleads.loginCustomerId=INSERT_LOGIN_CUSTOMER_ID_HERE
Przed uruchomieniem żądań interfejsu API utwórz instancję GoogleAdsClient. Domyślnie fromPropertiesFile() wczytuje dane logowania z pliku ads.properties znajdującego się w katalogu głównym:
GoogleAdsClient googleAdsClient;
try {
googleAdsClient = GoogleAdsClient.newBuilder().fromPropertiesFile().build();
} catch (IOException e) {
System.err.printf("Failed to create GoogleAdsClient: %s%n", e);
throw new RuntimeException("Initialization failed", e);
}
Następnie uruchom raport kampanii za pomocą usługi GoogleAdsService.SearchStream, aby efektywnie przesyłać strumieniowo duże zbiory wyników i pobierać kampanie na koncie:
private void runExample(GoogleAdsClient googleAdsClient, long customerId) {
try (GoogleAdsServiceClient googleAdsServiceClient =
googleAdsClient.getLatestVersion().createGoogleAdsServiceClient()) {
String query = "SELECT campaign.id, campaign.name FROM campaign ORDER BY campaign.id";
// Constructs the SearchGoogleAdsStreamRequest.
SearchGoogleAdsStreamRequest request =
SearchGoogleAdsStreamRequest.newBuilder()
.setCustomerId(Long.toString(customerId))
.setQuery(query)
.build();
// Creates and issues a search Google Ads stream request that will retrieve all campaigns.
ServerStream<SearchGoogleAdsStreamResponse> stream =
googleAdsServiceClient.searchStreamCallable().call(request);
// Iterates through and prints all of the results in the stream response.
for (SearchGoogleAdsStreamResponse response : stream) {
for (GoogleAdsRow googleAdsRow : response.getResultsList()) {
System.out.printf(
"Campaign with ID %d and name '%s' was found.%n",
googleAdsRow.getCampaign().getId(), googleAdsRow.getCampaign().getName());
}
}
}
}
C#
Pakiety biblioteki klienta są publikowane w repozytorium NuGet.org.
Zacznij od dodania odwołania do pakietu NuGet do Google.Ads.GoogleAds
pakietu:
dotnet add package Google.Ads.GoogleAds --version 27.4.0Aby wykonywać wywołania interfejsu API, utwórz obiekt GoogleAdsConfig na podstawie ustawień konfiguracji (np. appsettings.json, zmiennych środowiskowych lub ustawień niestandardowych) i przekaż go, aby zainicjować instancję GoogleAdsClient:
GoogleAdsConfig config = new GoogleAdsConfig()
{
OAuth2Mode = OAuth2Flow.SERVICE_ACCOUNT,
OAuth2SecretsJsonPath = "JSON_KEY_FILE_PATH",
LoginCustomerId = "INSERT_LOGIN_CUSTOMER_ID_HERE"
};
GoogleAdsClient client = new GoogleAdsClient(config);
Następnie uruchom raport kampanii, używając metody
GoogleAdsService.SearchStream
w celu pobrania kampanii na koncie. Ten przewodnik nie zawiera szczegółowych informacji o raportowaniu.
public void Run(GoogleAdsClient client, long customerId)
{
// Get the GoogleAdsService.
GoogleAdsServiceClient googleAdsService = client.GetService(
Services.V25.GoogleAdsService);
// Create a query that will retrieve all campaigns.
string query = @"SELECT
campaign.id,
campaign.name,
campaign.network_settings.target_content_network
FROM campaign
ORDER BY campaign.id";
try
{
// Issue a search request.
googleAdsService.SearchStream(customerId.ToString(), query,
delegate (SearchGoogleAdsStreamResponse resp)
{
foreach (GoogleAdsRow googleAdsRow in resp.Results)
{
Console.WriteLine("Campaign with ID {0} and name '{1}' was found.",
googleAdsRow.Campaign.Id, googleAdsRow.Campaign.Name);
}
}
);
}
catch (GoogleAdsException e)
{
Console.WriteLine("Failure:");
Console.WriteLine($"Message: {e.Message}");
Console.WriteLine($"Failure: {e.Failure}");
Console.WriteLine($"Request ID: {e.RequestId}");
throw;
}
}
PHP
Pakiety biblioteki klienta są publikowane w repozytorium Packagist.
Sprawdź, czy masz zainstalowaną zgodną wersję PHP i Composer, a potem przejdź do katalogu głównego projektu i uruchom to polecenie, aby zainstalować bibliotekę i jej zależności w katalogu vendor/ projektu:
composer require googleads/google-ads-php:35.1.0Utwórz kopię pliku
google_ads_php.ini
z repozytorium GitHub, zapisz ją w katalogu głównym lub w katalogu głównym projektu i zmodyfikuj, aby uwzględnić swoje dane logowania:
[GOOGLE_ADS]
loginCustomerId = "INSERT_LOGIN_CUSTOMER_ID_HERE"
[OAUTH2]
jsonKeyFilePath = "JSON_KEY_FILE_PATH"
scopes = "https://www.googleapis.com/auth/adwords"
Utwórz instancję GoogleAdsClient za pomocą pliku konfiguracji google_ads_php.ini:
use Google\Ads\GoogleAds\Lib\OAuth2TokenBuilder;
use Google\Ads\GoogleAds\Lib\V25\GoogleAdsClientBuilder;
$oauth2Credential = (new OAuth2TokenBuilder())
->fromFile('/path/to/google_ads_php.ini')
->build();
$googleAdsClient = (new GoogleAdsClientBuilder())
->fromFile('/path/to/google_ads_php.ini')
->withOAuth2Credential($oauth2Credential)
->build();
Następnie wygeneruj raport o kampaniach, korzystając z metody
GoogleAdsService.SearchStream
w celu pobrania kampanii na koncie:
public static function runExample(GoogleAdsClient $googleAdsClient, int $customerId)
{
$googleAdsServiceClient = $googleAdsClient->getGoogleAdsServiceClient();
// Creates a query that retrieves all campaigns.
$query = 'SELECT campaign.id, campaign.name FROM campaign ORDER BY campaign.id';
// Issues a search stream request.
/** @var GoogleAdsServerStreamDecorator $stream */
$stream = $googleAdsServiceClient->searchStream(
SearchGoogleAdsStreamRequest::build($customerId, $query)
);
// Iterates over all rows in all messages and prints the requested field values for
// the campaign in each row.
foreach ($stream->iterateAllElements() as $googleAdsRow) {
/** @var GoogleAdsRow $googleAdsRow */
printf(
"Campaign with ID %d and name '%s' was found.%s",
$googleAdsRow->getCampaign()->getId(),
$googleAdsRow->getCampaign()->getName(),
PHP_EOL
);
}
}
Python
Biblioteka klienta interfejsu Google Ads API dla języka Python jest rozpowszechniana w PyPI. Sprawdź, czy masz zainstalowaną obsługiwaną wersję Pythona, a następnie zainstaluj bibliotekę za pomocą tego polecenia:pip
python -m pip install google-ads==33.0.0Aby uwierzytelnić wywołania interfejsu API, skonfiguruj plik google-ads.yaml:
- Pobierz kopię przykładowego pliku
google-ads.yamlz repozytorium GitHub. - Zapisz plik w katalogu głównym (
~/google-ads.yaml) lub w niestandardowej ścieżce. Otwórz aplikację
google-ads.yamli zaktualizuj ją, podając swoje dane logowania:login_customer_id: INSERT_LOGIN_CUSTOMER_ID_HERE json_key_file_path: JSON_KEY_FILE_PATHSkonfiguruj rejestrowanie przed zainicjowaniem klienta, aby biblioteka rejestrowała ostrzeżenia dotyczące inicjowania lub konfiguracji. W tym przykładzie skonfigurujemy rejestrator biblioteki tak, aby wysyłał logi
INFOna standardowe wyjście (stdout):
import logging
import sys
logger = logging.getLogger("google.ads.googleads.client")
logger.setLevel(logging.INFO)
logger.addHandler(logging.StreamHandler(sys.stdout))
Utwórz instancję GoogleAdsClient, wywołując metodę
GoogleAdsClient.load_from_storage i przekazując ścieżkę do pliku
google-ads.yaml:
from google.ads.googleads.client import GoogleAdsClient
client = GoogleAdsClient.load_from_storage("path/to/google-ads.yaml")
Jeśli pominiesz argument ścieżki, load_from_storage() domyślnie wyszuka plik konfiguracji w katalogu głównym (~/google-ads.yaml).
Następnie wygeneruj raport o kampaniach, korzystając z metody
GoogleAdsService.SearchStream
w celu pobrania kampanii na koncie:
def main(client: GoogleAdsClient, customer_id: str) -> None:
ga_service: GoogleAdsServiceClient = client.get_service("GoogleAdsService")
query: str = """
SELECT
campaign.id,
campaign.name
FROM campaign
ORDER BY campaign.id"""
# Issues a search request using streaming.
stream: Iterator[SearchGoogleAdsStreamResponse] = ga_service.search_stream(
customer_id=customer_id, query=query
)
for batch in stream:
rows: List[GoogleAdsRow] = batch.results
for row in rows:
print(
f"Campaign with ID {row.campaign.id} and name "
f'"{row.campaign.name}" was found.'
)
Ruby
Gemy Ruby dla biblioteki klienta są publikowane w RubyGems. Sprawdź, czy masz zainstalowaną obsługiwaną wersję Ruby, i użyj Bundlera, aby zainstalować bibliotekę:
Dodaj gem do pliku
Gemfileaplikacji:gem 'google-ads-googleads', '~> 45.1.0'Zainstaluj gem, uruchamiając polecenie:
bundle install
Aby skonfigurować dane logowania:
- Skopiuj przykładowy plik
google_ads_config.rbz repozytorium GitHub. - Zapisz plik w katalogu głównym projektu lub w katalogu głównym użytkownika (
~). Otwórz plik
google_ads_config.rbi zastąp wartości zastępcze danymi logowania do interfejsu Google Ads API:Google::Ads::GoogleAds::Config.new do |c| c.login_customer_id = 'INSERT_LOGIN_CUSTOMER_ID_HERE' c.keyfile = 'JSON_KEY_FILE_PATH' endUtwórz instancję
GoogleAdsClient, przekazując ścieżkę do pliku konfiguracji (google_ads_config.rb):
client = Google::Ads::GoogleAds::GoogleAdsClient.new(
'path/to/google_ads_config.rb'
)
Następnie wygeneruj raport o kampaniach, korzystając z metody
GoogleAdsService.SearchStream
w celu pobrania kampanii na koncie:
def get_campaigns(customer_id)
# GoogleAdsClient will read a config file from
# ENV['HOME']/google_ads_config.rb when called without parameters
client = Google::Ads::GoogleAds::GoogleAdsClient.new
responses = client.service.google_ads.search_stream(
customer_id: customer_id,
query: 'SELECT campaign.id, campaign.name FROM campaign ORDER BY campaign.id',
)
responses.each do |response|
response.results.each do |row|
puts "Campaign with ID #{row.campaign.id} and name '#{row.campaign.name}' was found."
end
end
end
Perl
Biblioteka klienta Perl jest rozpowszechniana w CPAN i wymaga Perla w wersji 5.28 lub nowszej oraz menedżera pakietów cpan lub cpanm.
Sklonuj repozytorium
google-ads-perlw wybranym katalogu:git clone https://github.com/googleads/google-ads-perl.gitPrzejdź do katalogu
google-ads-perli uruchom te polecenia, aby zainstalować wymagane zależności i utworzyć bibliotekę:cd google-ads-perl cpan install Module::Build perl Build.PL perl Build installdeps perl Build perl Build install
Aby skonfigurować dane logowania:
Skopiuj przykładowy plik konfiguracyjny
googleads.propertiesz repozytorium GitHub do katalogu głównego~/googleads.properties:cp googleads.properties ~/googleads.propertiesEdytuj
~/googleads.properties, aby dodać swoje dane logowania:jsonKeyFilePath=JSON_KEY_FILE_PATH loginCustomerId=INSERT_LOGIN_CUSTOMER_ID_HEREUtwórz instancję
Client, przekazując ścieżkę do skonfigurowanego plikugoogleads.properties(np.~/googleads.properties):
my $api_client = Google::Ads::GoogleAds::Client->new({
properties_file => "/path/to/googleads.properties"
});
Następnie wygeneruj raport o kampaniach, korzystając z metody
GoogleAdsService.SearchStream
w celu pobrania kampanii na koncie:
sub get_campaigns {
my ($api_client, $customer_id) = @_;
# Create a search Google Ads stream request that will retrieve all campaigns.
my $search_stream_request =
Google::Ads::GoogleAds::V25::Services::GoogleAdsService::SearchGoogleAdsStreamRequest
->new({
customerId => $customer_id,
query =>
"SELECT campaign.id, campaign.name FROM campaign ORDER BY campaign.id"
});
# Get the GoogleAdsService.
my $google_ads_service = $api_client->GoogleAdsService();
my $search_stream_handler =
Google::Ads::GoogleAds::Utils::SearchStreamHandler->new({
service => $google_ads_service,
request => $search_stream_request
});
# Issue a search request and process the stream response to print the requested
# field values for the campaign in each row.
$search_stream_handler->process_contents(
sub {
my $google_ads_row = shift;
printf "Campaign with ID %d and name '%s' was found.\n",
$google_ads_row->{campaign}{id}, $google_ads_row->{campaign}{name};
});
return 1;
}
Po uruchomieniu skrypt przesyła strumieniowo pasujące wiersze i wyświetla identyfikator oraz nazwę każdej kampanii na Twoim koncie.
curl
Zacznij od ustawienia konta usługi jako aktywnych danych logowania w interfejsie wiersza poleceń gcloud.
gcloud auth login --cred-file=JSON_KEY_FILE_PATHNastępnie pobierz token dostępu OAuth 2.0 dla interfejsu Google Ads API.
gcloud auth \
print-access-token \
--scopes='https://www.googleapis.com/auth/adwords'Utwórz plik o nazwie query.json zawierający żądanie w języku zapytań Google Ads (GAQL):
{
"query": "SELECT campaign.id, campaign.name, campaign.network_settings.target_content_network FROM campaign ORDER BY campaign.id"
}
Aby pobrać kampanie na koncie, uruchom raport kampanii, korzystając z metody
GoogleAdsService.SearchStream:
curl -i -X POST \
https://googleads.googleapis.com/v25/customers/CUSTOMER_ID/googleAds:searchStream \
-H "Content-Type: application/json" \
-H "Authorization: Bearer ACCESS_TOKEN" \
-H "login-customer-id: LOGIN_CUSTOMER_ID" \
--data-binary "@query.json"Jeśli podczas wykonywania pierwszego wywołania napotkasz błędy, zapoznaj się z artykułem Obsługa błędów interfejsu API, aby uzyskać wskazówki dotyczące rozwiązywania problemów.