İstemci Kitaplıkları

Google Ads API istemci kitaplıkları, Google Ads API işlevselliğinin üst düzey görünümlerini ve temel yapı taşlarını sunarak uygulamaların hızlı bir şekilde geliştirilmesini kolaylaştırır. API'yi kullanmaya yeni başladıysanız bir istemci kitaplığıyla başlayın.

İstemci kitaplığı Kaynak Dağıtım Kod örnekleri
Java google-ads-java Maven, tar.gz, zip GitHub'da göster
.NET google-ads-dotnet NuGet, tar.gz, zip GitHub'da göster
PHP google-ads-php Composer, tar.gz, zip GitHub'da göster
Python google-ads-python PyPI, tar.gz, zip GitHub'da göster
Ruby google-ads-ruby RubyGems, tar.gz, zip GitHub'da göster
Perl google-ads-perl CPAN, tar.gz, zip GitHub'da göster

Topluluk kitaplıkları

Açık kaynak topluluğu tarafından yönetilen birkaç kitaplık olduğunu biliyoruz. İlgilenen geliştiricilerin bu kaynakları bulmasına yardımcı olmak için bu listeyi güncel tutuyoruz. Bu kitaplıkları test etmez, bunlara katkıda bulunmaz veya bunları sürdürmeyiz. Bu nedenle, bunları kendi sorumluluğunuzda kullanın. Sorularınızı açık kaynak projelerinin sahiplerine yönlendirmeniz gerekir.

Eksik bıraktığımız bir kitaplık olduğunu biliyorsanız sayfanın üst kısmındaki Geri bildirim gönder'i tıklayarak bize bildirin.

Desteklenen API sürümleri

Tabloda, hangi istemci kitaplıklarının hangi API sürümleriyle çalıştığı gösterilmektedir.

Listelenen minimum istemci kitaplığı sürümü, ana Google Ads API sürümü (ör. v26) için yeterlidir. Alt sürümler için gereken istemci kitaplığı sürümünü görmek üzere bağlantılı Değişiklik günlüğüne bakın.

Java

Değişiklik günlüğü

Java için istemci kitaplığı
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#

Değişiklik günlüğü

.NET için istemci kitaplığı
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

Değişiklik günlüğü

PHP için istemci kitaplığı
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

Değişiklik günlüğü

Python için istemci kitaplığı
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

Değişiklik günlüğü

Ruby için istemci kitaplığı
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

Değişiklik günlüğü

Perl için istemci kitaplığı
v26 Min: 36.0.0
Max: -
v25 Min: 33.0.0
Max: -
v24 Min: 32.0.0
Max: -
v23 Min: 31.0.0
Max: -

Yapılandırma

Her Google Ads API istemci kitaplığı, davranışını özelleştirmek için kullanabileceğiniz farklı yapılandırma ayarları ve yükleme yöntemleri sağlar.

İstemci kitaplıklarını yapılandırmak için kullanabileceğiniz standart ortam değişkenleri şunlardır:

  • İstemci kitaplığı
    • GOOGLE_ADS_CONFIGURATION_FILE_PATH: Yapılandırma dosyasının yolu (Java (fromPropertiesFile()), Perl (Client->new()), PHP (fromFile()), Python (load_from_storage(), ayrıca load_from_env() tarafından da kontrol edilir) ve Ruby'de (GoogleAdsClient.new) açık bir yol bağımsız değişkeni olmadan bir yapılandırma dosyasından yükleme yaparken otomatik olarak okunur; .NET dilinde bu değişkeni config.TryLoadFromEnvironmentFilePath kullanarak açıkça yükleyin veya yapılandırma dosyalarını LoadFromSettingsJson, LoadFromConfigurationSection ya da LoadFromConfigurationRoot kullanarak yükleyin).
  • OAuth2
    • Uygulama modu
      • GOOGLE_ADS_CLIENT_ID: Bu değeri OAuth2 istemci kimliğiniz olarak ayarlayın.
      • GOOGLE_ADS_CLIENT_SECRET: Bu değeri OAuth2 istemci gizli anahtarınız olarak ayarlayın.
      • GOOGLE_ADS_REFRESH_TOKEN: OAuth2 jetonlarını yeniden kullanmak istiyorsanız bu değeri önceden oluşturulmuş bir OAuth2 yenileme jetonu olarak ayarlayın. Bu ayar isteğe bağlıdır.
    • Hizmet hesabı modu
      • GOOGLE_ADS_JSON_KEY_FILE_PATH: Bu değeri OAuth2 JSON anahtar dosyanızın yoluna ayarlayın (.NET içinde GOOGLE_ADS_OAUTH2_MODE değerini de SERVICE_ACCOUNT olarak ayarlayın, çünkü OAuth2Mode varsayılan olarak APPLICATION'tır; v32.1.0'dan önceki PHP sürümlerinde veya özel kapsamlar kullanılırken google_ads_php.ini içinde [OAUTH2] scopes değerini de ayarlayın ya da withScopes() işlevini çağırın, çünkü fromEnvironmentVariables(), OAuth2 kapsamlarını bir ortam değişkeninden okumaz).
      • GOOGLE_ADS_IMPERSONATED_EMAIL: Bu değeri, Google Workspace alan genelinde yetki özelliğini kullanırken kimliğine büründüğünüz hesabın e-posta adresi olarak ayarlayın. Bu ayar isteğe bağlıdır.
    • Uygulama Varsayılan Kimlik Bilgileri modu
      • GOOGLE_ADS_USE_APPLICATION_DEFAULT_CREDENTIALS: Uygulama Varsayılan Kimlik Bilgileri'ni (ADC) kullanarak kimlik doğrulaması yapmak için bu değeri true olarak ayarlayın. Java v41.1.0 ve sonraki sürümler, Python v28.3.0 ve sonraki sürümler, Ruby v36.1.0 ve sonraki sürümlerde desteklenir (.NET v24.1.0 ve sonraki sürümlerde, LoadFromEnvironmentVariables() bunun yerine önek içermeyen USE_APPLICATION_DEFAULT_CREDENTIALS değişkenini okur veya GoogleAdsConfig üzerinde UseApplicationDefaultCredentials = true değerini ayarlar; PHP'de, açık OAuth2 kimlik bilgileri ayarlanmadığında OAuth2TokenBuilder otomatik olarak ADC'ye geri döner; Perl, ADC'yi desteklemez).
  • Google Ads API
    • GOOGLE_ADS_LOGIN_CUSTOMER_ID: Bu, istekte kullanılacak yetkili müşterinin kısa çizgisiz müşteri kimliğidir (-).
    • GOOGLE_ADS_LINKED_CUSTOMER_ID: Bu üstbilgi yalnızca Google Ads kullanıcı arayüzündeki Bağlı Hesaplar (Google Ads API'deki AccountLink kaynağı) üzerinden izin verildiğinde bir öğenin kaynaklarını güncelleyen yöntemler için gereklidir. Bu değeri, belirtilen müşteri kimliğinin kaynaklarını güncelleyen veri sağlayıcının müşteri kimliğine ayarlayın. Bu kod, tire işareti olmadan (-) ayarlanmalıdır. Bağlı hesaplar hakkında daha fazla bilgi edinmek için Yardım Merkezi'ni ziyaret edin.

Ortam değişkenleri genellikle $HOME dizininde bulunan .bashrc veya .bash_profile dosyası gibi bir bash yapılandırma dosyasında tanımlanır. Ayrıca komut satırı kullanılarak da tanımlanabilirler.

Terminal kullanarak .bashrc dosyasıyla ortam değişkeni tanımlamak için uygulayabileceğiniz bazı temel adımlar şunlardır:

# 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

Ortam değişkenleri, terminal örneğinizde doğrudan komut satırından da ayarlanabilir:

export GOOGLE_ADS_CLIENT_ID=1234567890

Diğer bir alternatif ise ortam değişkenlerini kullanan komutu çağırırken ortam değişkenlerini ayarlamaktır:

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

Varlıkları getirme

GoogleAdsService.SearchStream genellikle varlıkları getirmek için kullanılır ve sonuçlar satır akışı olarak döndürülür. Alternatif olarak, güvenilir olmayan bir internet bağlantısı üzerinden varlıkları getirmek için GoogleAdsService.Search kullanabilirsiniz. GoogleAdsService.Search sonuçları sayfa başına 10.000 satırlık sabit sayfa boyutlarında döndürür.

İstemci kitaplıkları, sonuçları yinelediğinizde otomatik olarak sayfalandırma uygular. Böylece sonuçları sırayla indirip tek seferde işleyebilirsiniz.

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.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

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

Kod örnekleri

Google Ads API'deki bazı yaygın işlevlerle ilgili kod örneklerimize göz atın.