Clientbibliotheken

Die Google Ads API-Clientbibliotheken bieten allgemeine Ansichten und grundlegende Bausteine der Google Ads API-Funktionen, sodass sich Apps schnell entwickeln lassen. Wenn Sie mit der API noch nicht vertraut sind, beginnen Sie mit einer Clientbibliothek.

In der folgenden Tabelle sind die offiziellen Clientbibliotheken und Links zu den Einrichtungsanleitungen, Quell-Repositories, Paketen und Codebeispielen aufgeführt:

Clientbibliothek Anleitungen für die Einrichtung und Nutzung Quelle Vertrieb Codebeispiele
Java Grundlegende Verwendung, Konfiguration, Authentifizierung, Logging, Feldmasken, Ressourcennamen google-ads-java Maven, tar.gz, zip Auf GitHub ansehen
.NET Grundlegende Verwendung, Konfiguration, Authentifizierung, Logging, Feldmasken, Ressourcennamen google-ads-dotnet NuGet, tar.gz, zip Auf GitHub ansehen
PHP Grundlegende Verwendung, Konfiguration, Authentifizierung, Logging, Feldmasken, Ressourcennamen google-ads-php Composer, tar.gz, zip Auf GitHub ansehen
Python Installation, Konfiguration, Authentifizierung, Logging, Feldmasken, Ressourcennamen google-ads-python PyPI, tar.gz, zip Auf GitHub ansehen
Ruby Grundlegende Verwendung, Konfiguration, Authentifizierung, Logging, Feldmasken, Ressourcennamen google-ads-ruby RubyGems, tar.gz, zip Auf GitHub ansehen
Perl Grundlegende Verwendung, Konfiguration, Authentifizierung, Logging, Feldmasken, Ressourcennamen google-ads-perl CPAN, tar.gz, zip Auf GitHub ansehen

Community-Bibliotheken

Uns sind mehrere Bibliotheken bekannt, die von der Open-Source-Community verwaltet werden. Wir führen diese Liste, damit interessierte Entwickler sie finden können. Wir testen diese Bibliotheken nicht, tragen nicht zu ihnen bei und pflegen sie nicht. Die Verwendung erfolgt auf eigene Gefahr. Bei Fragen wenden Sie sich bitte an die Inhaber der Open-Source-Projekte.

Wenn Sie eine Bibliothek kennen, die wir übersehen haben, klicken Sie oben auf der Seite auf Feedback geben und teilen Sie uns dies mit.

Unterstützte API-Versionen

In der Tabelle sehen Sie, welche Clientbibliotheken mit welchen API-Versionen funktionieren.

Die aufgeführte Mindestversion der Clientbibliothek ist für die Hauptversion der Google Ads API (z. B. v26) ausreichend. Die erforderliche Version der Clientbibliothek für Nebenversionen finden Sie im verknüpften Änderungsprotokoll.

Java

Änderungsprotokoll

Clientbibliothek für Java
v26 Min: 48.0.0
Max: -
v25 Min: 44.0.0
Max: -
v24 Min: 43.0.0
Max: -
v23 Min: 42.0.0
Max: -

C#

Änderungsprotokoll

Clientbibliothek für .NET
v26 Min: 27.5.0
Max: -
v25 Min: 26.1.0
Max: -
v24 Min: 25.3.0
Max: -
v23 Min: 25.1.0
Max: -

PHP

Änderungsprotokoll

Clientbibliothek für PHP
v26 Min: 35.2.0
Max: -
v25 Min: 33.6.0
Max: -
v24 Min: 33.3.0
Max: -
v23 Min: 32.2.0
Max: -

Python

Änderungsprotokoll

Clientbibliothek für Python
v26 Min: 34.0.0
Max: -
v25 Min: 31.2.0
Max: -
v24 Min: 30.1.0
Max: -
v23 Min: 29.2.0
Max: -

Ruby

Änderungsprotokoll

Clientbibliothek für Ruby
v26 Min: 46.0.0
Max: -
v25 Min: 43.0.0
Max: -
v24 Min: 40.0.0
Max: -
v23 Min: 38.0.0
Max: -

Perl

Änderungsprotokoll

Clientbibliothek für Perl
v26 Min: 36.0.0
Max: -
v25 Min: 33.0.0
Max: -
v24 Min: 32.0.0
Max: -
v23 Min: 31.0.0
Max: -

Konfiguration

Jede Google Ads API-Clientbibliothek bietet verschiedene Konfigurationseinstellungen und Lademethoden, mit denen Sie das Verhalten anpassen können.

Hier sind die Standardumgebungsvariablen, mit denen Sie die Clientbibliotheken konfigurieren können:

  • Clientbibliothek
    • GOOGLE_ADS_CONFIGURATION_FILE_PATH: Pfad zur Konfigurationsdatei (wird automatisch gelesen, wenn sie aus einer Konfigurationsdatei ohne explizites Pfadargument in Java (fromPropertiesFile()), Perl (Client->new()), PHP (fromFile()), Python (load_from_storage(), wird auch von load_from_env() geprüft) und Ruby (GoogleAdsClient.new) geladen wird; in .NET laden Sie diese Variable explizit mit config.TryLoadFromEnvironmentFilePath oder laden Sie Konfigurationsdateien mit LoadFromSettingsJson, LoadFromConfigurationSection oder LoadFromConfigurationRoot).
  • OAuth2
    • Anwendungsmodus
      • GOOGLE_ADS_CLIENT_ID: Setzen Sie diesen Wert auf Ihre OAuth2-Client-ID.
      • GOOGLE_ADS_CLIENT_SECRET: Legen Sie diesen Wert auf Ihren OAuth2-Clientschlüssel fest.
      • GOOGLE_ADS_REFRESH_TOKEN: Setzen Sie diesen Wert auf ein vorab generiertes OAuth2-Aktualisierungstoken, wenn Sie OAuth2-Tokens wiederverwenden möchten. Diese Einstellung ist optional.
    • Dienstkontomodus
      • GOOGLE_ADS_JSON_KEY_FILE_PATH: Legen Sie diesen Wert auf den Pfad Ihrer OAuth2-JSON-Schlüsseldatei fest. Legen Sie in .NET auch GOOGLE_ADS_OAUTH2_MODE auf SERVICE_ACCOUNT fest, da OAuth2Mode standardmäßig auf APPLICATION gesetzt ist. Legen Sie in PHP-Versionen vor v32.1.0 oder bei Verwendung benutzerdefinierter Bereiche auch [OAUTH2] scopes in google_ads_php.ini fest oder rufen Sie withScopes() auf, da fromEnvironmentVariables() keine OAuth2-Bereiche aus einer Umgebungsvariablen liest.
      • GOOGLE_ADS_IMPERSONATED_EMAIL: Legen Sie diesen Wert auf die E-Mail-Adresse des Kontos fest, dessen Identität Sie bei der Verwendung der domainweiten Delegierung von Google Workspace übernehmen. Diese Einstellung ist optional.
    • Modus „Standardanmeldedaten für Anwendungen“
      • GOOGLE_ADS_USE_APPLICATION_DEFAULT_CREDENTIALS: Setzen Sie diesen Wert auf true, um sich mit Standardanmeldedaten für Anwendungen (Application Default Credentials, ADC) zu authentifizieren. Unterstützt in Java v41.1.0 und höher, Python v28.3.0 und höher und Ruby v36.1.0 und höher (in .NET v24.1.0 und höher liest LoadFromEnvironmentVariables() stattdessen die Variable USE_APPLICATION_DEFAULT_CREDENTIALS ohne Präfix oder legt UseApplicationDefaultCredentials = true auf GoogleAdsConfig fest; in PHP greift OAuth2TokenBuilder automatisch auf ADC zurück, wenn keine expliziten OAuth2-Anmeldedaten festgelegt sind; Perl unterstützt ADC nicht).
  • Google Ads API
    • GOOGLE_ADS_LOGIN_CUSTOMER_ID: Dies ist die Kundennummer des autorisierten Kunden, die in der Anfrage verwendet werden soll, ohne Bindestriche (-).
    • GOOGLE_ADS_LINKED_CUSTOMER_ID: Dieser Header ist nur für Methoden erforderlich, mit denen die Ressourcen einer Entität aktualisiert werden, wenn die Berechtigung über verknüpfte Konten in der Google Ads-Benutzeroberfläche (AccountLink-Ressource in der Google Ads API) erteilt wurde. Legen Sie diesen Wert auf die Kundennummer des Datenanbieters fest, der die Ressourcen der angegebenen Kundennummer aktualisiert. Sie muss ohne Bindestriche (-) angegeben werden. Weitere Informationen zu verknüpften Konten finden Sie in der Hilfe.

Umgebungsvariablen werden häufig in einer Bash-Konfigurationsdatei wie einer .bashrc- oder .bash_profile-Datei im Verzeichnis $HOME definiert. Sie können auch über die Befehlszeile definiert werden.

Hier sind einige grundlegende Schritte, um eine Umgebungsvariable mit einer .bashrc-Datei über ein Terminal zu definieren:

# Append the line "export GOOGLE_ADS_CLIENT_ID=1234567890" to
# the bottom of your .bashrc file.
echo "export GOOGLE_ADS_CLIENT_ID=1234567890" >> ~/.bashrc

# Update your bash environment to use the most recently updated
# version of your .bashrc file.
source ~/.bashrc

Umgebungsvariablen können auch direkt über die Befehlszeile in Ihrer Terminalinstanz festgelegt werden:

export GOOGLE_ADS_CLIENT_ID=1234567890

Eine weitere Alternative besteht darin, Umgebungsvariablen beim Aufrufen des Befehls festzulegen, der sie verwendet:

GOOGLE_ADS_CLIENT_ID=1234567890 php /path/to/script/that/uses/envvar.php

Entitäten abrufen

GoogleAdsService.SearchStream wird normalerweise zum Abrufen von Entitäten verwendet. Die Ergebnisse werden als Stream von Zeilen zurückgegeben. Alternativ können Sie GoogleAdsService.Search verwenden, um Entitäten über eine unzuverlässige Internetverbindung abzurufen. GoogleAdsService.Search gibt Ergebnisse als feste Seitengrößen von 10.000 Zeilen pro Seite zurück.

Die Clientbibliotheken implementieren automatisch die Paginierung, wenn Sie Ergebnisse iterieren, sodass Sie sie nacheinander herunterladen und alle auf einmal verarbeiten können.

Java

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#

public void Run(GoogleAdsClient client, long customerId)
{
    // Get the GoogleAdsService.
    GoogleAdsServiceClient googleAdsService = client.GetService(
        Services.V26.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

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

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

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

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::V26::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

Codebeispiele

Hier finden Sie Codebeispiele für einige gängige Funktionen in der Google Ads API.