In dieser Kurzanleitung erfahren Sie, wie Sie Ihren ersten API-Aufruf an die Google Ads API senden.
Wichtige Konzepte
- Google Cloud-Projekt: Ein Google Cloud-Projekt bildet die Grundlage für das Erstellen, Aktivieren und Verwenden aller Google-Dienste, einschließlich der Verwaltung von APIs und OAuth 2.0-API-Anmeldedaten. Sie können ein Projekt über die Google Cloud Console erstellen.
- API-Zugriffsebene: Die API-Zugriffsebene Ihres Google Cloud-Projekts steuert die Anzahl der API-Aufrufe, die Sie pro Tag senden können, und die Umgebungen, an die Sie API-Aufrufe senden können. Die API -Zugriffsebene Ihres Projekts ist auf der Übersichtsseite der Google Ads API Ihres Projekts aufgeführt.
- **Google Ads-Verwaltungskonto**:Ein Google Ads-Verwaltungskonto wird verwendet, um andere Google Ads-Konten zu verwalten. Das können Google Ads-Kundenkonten oder andere Google Ads-Verwaltungskonten sein.
- Google Ads-Kundenkonto:Das Google Ads-Konto, das zum Ausführen von Anzeigen verwendet wird, auf die Sie mit API-Aufrufen abzielen möchten.
- Kunden-ID:Die zehnstellige Nummer, die ein Google Ads-Kundenkonto identifiziert. Wenn Sie diese ID aus der Google Ads-Benutzeroberfläche kopiert haben, entfernen Sie die Bindestriche.
- **OAuth 2.0**:OAuth 2.0 ist ein Standardprotokoll der Branche für die Autorisierung, das von allen Google APIs verwendet wird. Sie benötigen ein Dienstkonto und einen Schlüssel, um OAuth 2.0-Anmeldedaten für API-Aufrufe zu generieren.
- **Dienstkonto**: Eine spezielle Art von Google Konto, das zu Ihrer Anwendung und nicht zu einem einzelnen Nutzer gehört. Es wird verwendet, um Ihre Anwendung bei der Google Ads API zu authentifizieren. Sie benötigen ein Google Cloud-Projekt, um ein Dienstkonto zu erhalten.
- Dienstkontoschlüssel:Eine JSON-Datei mit Anmeldedaten für die App, die den privaten Schlüssel für Ihr Dienstkonto enthält. Sie wird verwendet, um OAuth 2.0-Anmeldedaten zu generieren, um ein Dienstkonto bei einem Google Ads API-Aufruf zu authentifizieren. Sie benötigen ein Dienstkonto, um einen Dienstkontoschlüssel zu erhalten.
Vorbereitung
Führen Sie die folgenden Schritte aus, um einen Google Ads API-Aufruf zu senden.
Google API Console-Projekt für den Zugriff auf die Google Ads API konfigurieren
Das Google Cloud-Projekt wird zum Verwalten von Google APIs und OAuth 2.0-API-Anmeldedaten verwendet. Sie können Ihre vorhandenen Google Cloud-Projekte aufrufen oder ein neues erstellen, indem Sie die Google Cloud Console aufrufen.
Aktivieren Sie zuerst die Google Ads API in Ihrem Projekt:
Rufen Sie dann die Übersichtsseite der Google Ads API auf. Auf der Seite wird Ihre aktuelle API-Zugriffsebene angezeigt. Wenn Ihre aktuelle API-Zugriffsebene Test Account Access level ist, maximieren Sie den Abschnitt Apply for next access level. Folgen Sie der Anleitung, um die Explorer Access level zu beantragen.
Nachdem Sie den Antrag eingereicht haben, prüft Google ihn automatisch und stuft ihn in den meisten Fällen auf die Zugriffsebene „Explorer“ hoch. Wenn Sie keinen Zugriff auf die Explorer-Ebene erhalten haben, ist das kein Problem. In dieser Anleitung finden Sie die entsprechenden Anweisungen zum Konfigurieren Ihres Google Ads-Kundenkontos.
Dienstkonto erstellen
Für API-Aufrufe sind ein Dienstkonto und ein Dienstkontoschlüssel erforderlich. Wenn Sie bereits eine andere Google API verwenden und ein OAuth 2.0-Dienstkonto und einen Schlüssel erstellt haben, können Sie diesen Schritt überspringen und die vorhandenen Anmeldedaten wiederverwenden.
Dienstkonto und Schlüssel erstellen
- Wechseln Sie in der Google Cloud Console zu „Menü“ > IAM und Verwaltung > Dienstkonten.
- Wählen Sie Ihr Dienstkonto aus.
- Klicken Sie auf Schlüssel > Schlüssel hinzufügen > Neuen Schlüssel erstellen.
- Wählen Sie JSON aus und klicken Sie dann auf Erstellen.
Ihr neues öffentliches/privates Schlüsselpaar wird generiert und als neue Datei auf Ihren Computer heruntergeladen. Speichern Sie die heruntergeladene JSON-Datei als
credentials.jsonin Ihrem Arbeitsverzeichnis. Diese Datei ist die einzige Kopie dieses Schlüssels. - Klicken Sie auf Schließen.
Google Ads-Kundenkonto konfigurieren
Geben Sie zuerst das Google Ads-Konto an, für das Sie API-Aufrufe senden. Die Art des Kontos, für das Sie API-Aufrufe senden können, hängt von der API-Zugriffsebene Ihres Google Cloud-Projekts ab. Auf der Übersichtsseite der Google Ads API finden Sie Ihre API-Zugriffsebene.
Zugriffsebenen „Explorer“, „Basic“ und „Standard“
Sie können Aufrufe an Ihr Google Ads-Produktionskonto senden. Bei Bedarf können Sie jedoch ein Google Ads-Testkonto erstellen. Folgen Sie dazu der Anleitung auf dem Tab Test Account Access.
Zugriffsebene „Test Account Access“
Ihr Google Cloud-Projekt kann nicht verwendet werden, um API-Aufrufe an ein Google Ads-Produktionskonto zu senden. Sie können nur API-Aufrufe für Google Ads-Testkonten senden.
Google Ads-Testkonto erstellen
Mit der folgenden Anleitung wird ein Google Ads-Testverwaltungskonto und ein Google Ads-Testwerbetreibendenkonto darunter erstellt.
Klicken Sie auf die blaue Schaltfläche, um ein Google Ads-Testverwaltungskonto zu erstellen. Melden Sie sich bei Aufforderung mit einem Google-Konto an, das nicht mit Ihrem Google Ads-Produktionsverwaltungskonto verknüpft ist. Wenn Sie kein solches Konto haben, klicken Sie auf dieser Seite auf die Schaltfläche „Konto erstellen“ , um ein neues Google -Konto zu erstellen.
- Erstellen Sie in Ihrem Google Ads-Testverwaltungskonto ein Google Ads-Test Kundenkonto: Klicken Sie auf Konten > > Neues Konto erstellen und füllen Sie das Formular aus. Alle Google Ads-Konten, die Sie über Ihr Google Ads-Test Verwaltungskonto erstellen, sind automatisch Google Ads-Testkonten.
- Optional können Sie auf der Google Ads-Seite einige Kampagnen unter dem Google Ads-Testkunden konto erstellen.
Wenn Sie einen API-Aufruf an einen Google Ads-Kunden senden möchten, müssen Sie Ihrem Dienstkonto Zugriff auf das Google Ads-Kundenkonto gewähren und die entsprechenden Berechtigungen erteilen. Dazu benötigen Sie Administratorzugriff auf das Kundenkonto.
Dienstkonto Zugriff auf Ihr Google Ads Konto gewähren
- Melden Sie sich zuerst als Administrator in Ihrem Google Ads-Konto an.
- Rufen Sie Verwaltung > Zugriff und Sicherheit auf.
- Klicken Sie auf dem Tab Nutzer auf die Schaltfläche „
“.
- Geben Sie die E-Mail-Adresse des Dienstkontos in das Eingabefeld E-Mail ein.
Wählen Sie die entsprechende Zugriffsebene für das Konto aus und klicken Sie auf die
Schaltfläche Konto hinzufügen. Die Zugriffsebene „E-Mail“ wird für Dienstkonten nicht unterstützt.
- Dem Dienstkonto wird Zugriff gewährt.
- [Optional] Standardmäßig können Sie einem
Dienstkonto keinen Administratorzugriff gewähren. Wenn für Ihre API-Aufrufe Administratorzugriff erforderlich ist, können Sie den Zugriff so aktualisieren:
- Klicken Sie in der Spalte Zugriffsebene auf den Drop-down-Pfeil neben der Zugriffsebene des Dienstkontos.
- Wählen Sie in der Drop-down-Liste Administrator aus.
Tools und Clientbibliotheken herunterladen
Je nachdem, wie Sie API-Aufrufe senden möchten, können Sie entweder eine Clientbibliothek oder einen HTTP-Client herunterladen.
Clientbibliothek verwenden
Laden Sie eine Clientbibliothek Ihrer Wahl herunter und installieren Sie sie.
HTTP-Client (REST) verwenden
curl
Laden Sie curl herunter und installieren Sie es. Das ist ein Befehlszeilentool zum Übertragen von Daten über eine URL.
Google Cloud CLI
Folgen Sie der Anleitung, um die gcloud CLI zu installieren.
Die Anweisungen für den Rest dieser Anleitung wurden mit der folgenden Version des gcloud-Tools getestet und funktionieren möglicherweise nicht mit früheren Versionen, da sich das Anwendungsverhalten oder die Befehlszeilenoptionen unterscheiden.
:~$ 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.30API aufrufen
Wählen Sie Ihren bevorzugten Client aus, um eine Anleitung zum Senden eines API-Aufrufs zu erhalten:
Java
Die Clientbibliotheksartefakte werden im zentralen Maven Repository veröffentlicht. Fügen Sie die Clientbibliothek so als Abhängigkeit zu Ihrem Projekt hinzu:
Die Maven-Abhängigkeit ist:
<dependency>
<groupId>com.google.api-ads</groupId>
<artifactId>google-ads</artifactId>
<version>46.0.0</version>
</dependency>
Die Gradle-Abhängigkeit ist:
implementation 'com.google.api-ads:google-ads:46.0.0'
Wir empfehlen außerdem, die Google Ads API Bill of Materials (BOM) zu verwenden, um Abhängigkeitsversionen zu verwalten. Eine Anleitung finden Sie im BOM-Leitfaden.
Erstellen Sie eine Datei ~/ads.properties mit folgendem Inhalt:
api.googleads.serviceAccountSecretsPath=JSON_KEY_FILE_PATH
api.googleads.loginCustomerId=INSERT_LOGIN_CUSTOMER_ID_HERE
Erstellen Sie so ein GoogleAdsClient-Objekt:
GoogleAdsClient googleAdsClient = null;
try {
googleAdsClient = GoogleAdsClient.newBuilder().fromPropertiesFile().build();
} catch (FileNotFoundException fnfe) {
System.err.printf(
"Failed to load GoogleAdsClient configuration from file. Exception: %s%n",
fnfe);
System.exit(1);
} catch (IOException ioe) {
System.err.printf("Failed to create GoogleAdsClient. Exception: %s%n", ioe);
System.exit(1);
}
Führen Sie als Nächstes einen Kampagnenbericht mit der GoogleAdsService.SearchStream-Methode aus, um die
Kampagnen in Ihrem Konto abzurufen.
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#
Die Clientbibliothekspakete werden im Nuget.org
Repository veröffentlicht. Fügen Sie zuerst einen NuGet-Verweis auf das Paket Google.Ads.GoogleAds hinzu.
dotnet add package Google.Ads.GoogleAds --version 26.1.0Erstellen Sie ein GoogleAdsConfig-Objekt mit den entsprechenden Einstellungen und verwenden Sie es, um ein GoogleAdsClient-Objekt zu erstellen.
GoogleAdsConfig config = new GoogleAdsConfig()
{
OAuth2Mode = OAuth2Flow.SERVICE_ACCOUNT,
OAuth2SecretsJsonPath = "PATH_TO_CREDENTIALS_JSON",
LoginCustomerId = ******
};
GoogleAdsClient client = new GoogleAdsClient(config);
Führen Sie als Nächstes einen Kampagnenbericht mit der GoogleAdsService.SearchStream-Methode aus, um die
Kampagnen in Ihrem Konto abzurufen. In dieser Anleitung werden die Details der
Berichterstellung nicht behandelt.
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
Die Clientbibliothekspakete werden im Packagist
Repository veröffentlicht. Wechseln Sie zum Stammverzeichnis Ihres Projekts und führen Sie den folgenden Befehl aus, um die Bibliothek und alle ihre Abhängigkeiten im Verzeichnis vendor/ des Stammverzeichnisses Ihres Projekts zu installieren.
composer require googleads/google-ads-php:33.6.0Erstellen Sie eine Kopie der
google_ads_php.ini
Datei aus dem GitHub-Repository und ändern Sie sie, um Ihre Anmeldedaten einzufügen.
[GOOGLE_ADS]
loginCustomerId = "INSERT_LOGIN_CUSTOMER_ID_HERE"
[OAUTH2]
jsonKeyFilePath = "INSERT_ABSOLUTE_PATH_TO_OAUTH2_JSON_KEY_FILE_HERE"
scopes = "https://www.googleapis.com/auth/adwords"
Erstellen Sie eine Instanz des GoogleAdsClient-Objekts.
$oAuth2Credential = (new OAuth2TokenBuilder())
->fromFile('/path/to/google_ads_php.ini')
->build();
$googleAdsClient = (new GoogleAdsClientBuilder())
->fromFile('/path/to/google_ads_php.ini')
->withOAuth2Credential($oAuth2Credential)
->build();
Führen Sie als Nächstes einen Kampagnenbericht mit der GoogleAdsService.SearchStream-Methode aus, um die
Kampagnen in Ihrem Konto abzurufen.
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
Die Clientbibliothek wird auf PyPI
verteilt und kann mit dem pip
Befehl so installiert werden:
python -m pip install google-ads==31.2.0Erstellen Sie eine Kopie der
google-ads.yaml Datei aus dem
GitHub-Repository und ändern Sie sie, um Ihre Anmeldedaten einzufügen.
login_customer_id: INSERT_LOGIN_CUSTOMER_ID_HERE
json_key_file_path: JSON_KEY_FILE_PATH_HERE
Erstellen Sie eine GoogleAdsClient-Instanz, indem Sie die
GoogleAdsClient.load_from_storage-Methode aufrufen. Übergeben Sie den Pfad zu Ihrer google-ads.yaml-Datei als String an die Methode, wenn Sie sie aufrufen:
from google.ads.googleads.client import GoogleAdsClient
client = GoogleAdsClient.load_from_storage("path/to/google-ads.yaml")
Fügen Sie dem Logger der Bibliothek einen Handler hinzu, der angibt, wo Logs ausgegeben werden sollen.
Mit dem folgenden Befehl wird der Logger der Bibliothek angewiesen, Logs in der Konsole (stdout) auszugeben.
import logging
import sys
logger = logging.getLogger('google.ads.googleads.client')
logger.addHandler(logging.StreamHandler(sys.stdout))
Führen Sie als Nächstes einen Kampagnenbericht mit der GoogleAdsService.SearchStream-Methode aus, um die
Kampagnen in Ihrem Konto abzurufen.
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
Die Ruby-Gems für die Clientbibliothek werden auf der Rubygems-Website für das Gem hosting veröffentlicht. Die empfohlene Installationsmethode ist die Verwendung von Bundler. Fügen Sie Ihrem Gemfile eine Zeile hinzu:
gem 'google-ads-googleads', '~> 43.0.0'
Führen Sie dann diesen Befehl aus:
bundle installErstellen Sie eine Kopie der
google_ads_config.rb
Datei aus dem GitHub-Repository und ändern Sie sie, um Ihre Anmeldedaten einzufügen.
Google::Ads::GoogleAds::Config.new do |c|
c.login_customer_id = 'INSERT_LOGIN_CUSTOMER_ID_HERE'
c.keyfile = 'JSON_KEY_FILE_PATH'
end
Erstellen Sie eine GoogleAdsClient-Instanz, indem Sie den Pfad zu dieser Datei übergeben.
client = Google::Ads::GoogleAds::GoogleAdsClient.new('path/to/google_ads_config.rb')
Führen Sie als Nächstes einen Kampagnenbericht mit der GoogleAdsService.SearchStream-Methode aus, um die
Kampagnen in Ihrem Konto abzurufen.
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
Die Bibliothek wird auf
CPAN verteilt. Klonen Sie zuerst das google-ads-perl-Repository in das Verzeichnis Ihrer Wahl.
git clone https://github.com/googleads/google-ads-perl.gitWechseln Sie zum Verzeichnis google-ads-perl und führen Sie den folgenden Befehl in der Eingabeaufforderung aus, um alle Abhängigkeiten zu installieren, die für die Verwendung der Bibliothek erforderlich sind.
cd google-ads-perlcpan install Module::Buildperl Build.PLperl Build installdeps
Erstellen Sie eine Kopie der
googleads.properties
Datei aus dem GitHub-Repository und ändern Sie sie, um Ihre Anmeldedaten einzufügen.
jsonKeyFilePath=JSON_KEY_FILE_PATH
loginCustomerId=INSERT_LOGIN_CUSTOMER_ID_HERE
Erstellen Sie eine Client-Instanz, indem Sie den Pfad zu dieser Datei übergeben.
my $properties_file = "/path/to/googleads.properties";
my $api_client = Google::Ads::GoogleAds::Client->new({
properties_file => $properties_file
});
Führen Sie als Nächstes einen Kampagnenbericht mit der GoogleAdsService.SearchStream-Methode aus, um die
Kampagnen in Ihrem Konto abzurufen.
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;
}
curl
Legen Sie zuerst das Dienstkonto als aktive Anmeldedaten in der gcloud CLI fest.
gcloud auth login --cred-file=PATH_TO_CREDENTIALS_JSONRufen Sie dann ein OAuth 2.0-Zugriffstoken für die Google Ads API ab.
gcloud auth \
print-access-token \
--scopes='https://www.googleapis.com/auth/adwords'Führen Sie als Nächstes einen Kampagnenbericht mit der GoogleAdsService.SearchStream-Methode aus, um die
Kampagnen in Ihrem Konto abzurufen.
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 "developer-token: DEVELOPER_TOKEN" \
-H "login-customer-id: LOGIN_CUSTOMER_ID" \
--data-binary "@query.json"Der Inhalt von query.json sieht so aus:
{
"query": "SELECT campaign.id, campaign.name, campaign.network_settings.target_content_network FROM campaign ORDER BY campaign.id"
}
Wenn beim ersten Aufruf Fehler auftreten, finden Sie unter API-Fehler beheben eine Anleitung zur Fehlerbehebung.