Google Ads API ilk katılım kılavuzu

Bu kılavuzda, ilk katılım, kimlik doğrulama ve Google Ads API'ye ilk çağrınızı yapma ile ilgili tüm süreç ayrıntılı olarak açıklanmaktadır.

1. Ön koşullar ve hesap hiyerarşisi

Google Ads API ile etkileşime geçmeden önce hesap hiyerarşisini anlamanız ve doğru üst düzey hesap yapısına sahip olmanız gerekir.

• Yönetici Hesabı (MCC): Google Ads Yönetici Hesabı (eski adıyla Müşteri Merkezim), birden fazla müşteri hesabını görüntülemek ve yönetmek için kullanılan ana hesaptır. Google Ads API geliştirici jetonu için başvuruda bulunmak üzere bir yönetici hesabınız olmalıdır.
• Müşteri Hesabı: Kampanyaların, reklam gruplarının ve reklamların oluşturulduğu, faturalandırmanın yapılandırıldığı standart hesap.

Yapılacak İş: Yönetici hesabınız yoksa Google Ads yönetici hesapları sayfasından bir hesap oluşturun.

2. Geliştirici jetonu edinme

Geliştirici jetonu, uygulamanızı Google Ads API'de benzersiz bir şekilde tanımlar ve çağrı hacmi erişim katmanınızı kontrol eder.

İzlenecek adımlar

1. Google Ads yönetici hesabınızda oturum açın.
2. Araçlar ve ayarlar > Kurulum > API Merkezi'ne (veya Yönetici > API Merkezi) gidin.
3. Geliştirici ayrıntıları formunu doldurun ve API Hizmet Şartları'nı kabul edin.
4. Başvurunuzu gönderin.

Erişim düzeyleri

• Onay Bekliyor: Yeni oluşturulan jetonlar hemen "Beklemede" durumunu alır. Test Hesapları'na bağlanmak için bekleyen bir jeton kullanabilirsiniz ancak bu jeton, üretim hesaplarında çalışmaz.
• Temel Erişim: Onaylandıktan sonra günde en fazla 15.000 API işlemine izin verir.
• Standart Erişim: Gerekli Minimum İşlevler (GMİ) şartlarını karşılayan uygulamalar için sınırsız günlük API işlemleri.

3. Test hesapları oluşturma

Üretim hesaplarına karşı geliştirme ve test yapılması, istenmeyen reklam harcamalarına ve kampanya değişikliklerine yol açabilir. Tüm etkin geliştirme işlemlerinin test hesaplarında yapılması önemle tavsiye edilir.

Test yönetici hesabı oluşturma

1. Google Ads Testi Yönetici Hesabı oluşturma sayfasına gidin.
2. Üretim Google Ads yönetici hesabınıza henüz bağlı olmayan bir Google Hesabı ile oturum açın.
3. Açıklayıcı bir hesap adı girin (ör. MyCompany Test MCC).
4. Birincil kullanım olarak Başkalarının hesaplarını yönet'i seçin.
5. Fatura adresinizin bulunduğu ülkeyi, saat diliminizi ve para biriminizi seçin. Kaydet ve devam et'i tıklayın.

Test müşteri hesabı oluşturma

Test yöneticisi hesabınız oluşturulduktan sonra test kampanyaları yayınlamak için en az bir alt müşteri hesabı oluşturmanız gerekir.

1. Yeni oluşturduğunuz Test Yöneticisi Hesabı'nda oturum açın.
2. Soldaki gezinme menüsünden Hesaplar'ı tıklayın, ardından Alt hesap ayarları'nı (veya Performans'ı) seçin.
3. Mavi + (artı) düğmesini tıklayın ve Yeni hesap oluştur'u seçin.
4. Google Ads hesabını seçin.
5. Hesap adı girin (ör. Test Client Account A).
6. Saat dilimi ve para birimi seçip Kaydet ve devam et'i tıklayın.
7. Bu yeni müşteri hesabının 10 haneli müşteri kimliğini (ör. 1234567890, tire olmadan) not edin.

Test hesaplarıyla ilgili önemli kurallar

• Geliştirici Jetonu Kullanımı: Test yönetici hesabınızdan geliştirici jetonu için başvurmayın. Üretim yöneticisi hesabınızdaki bekleyen veya onaylanmış geliştirici jetonunu her zaman kullanın.
• Faturalandırma: Test hesapları gerçek reklam yayınlamaz. Bu nedenle, gerçek fatura bilgileri girmeniz gerekmez.

4. Google Cloud projesi kurulumu

Tüm API isteklerinin, Google Ads API'nin etkin olduğu bir Google Cloud projesi kullanılarak kimliği doğrulanmış olması gerekir.

API'yi etkinleştirme adımları

1. Google Cloud Console'a gidin.
2. Yeni bir proje oluşturun veya mevcut bir projeyi seçin.
3. API'ler ve Hizmetler > Kitaplık'a gidin.
4. Google Ads API'yi arayın ve Etkinleştir'i tıklayın.

Fiyatlandırma ve faturalandırma

• API Ücreti Yok: Google Cloud projesi oluşturma, Google Ads API'yi etkinleştirme ve OAuth 2.0 kimlik bilgileri oluşturma işlemleri % 100 ücretsizdir. Google, Google Ads API'nin kendisini çağırma veya kullanma konusunda herhangi bir ücret almaz.
• Diğer Bulut Kaynakları: Uygulamanızı barındırmak veya reklam verilerinizi depolamak için diğer faturalandırılabilir Google Cloud hizmetlerini (ör. Compute Engine, Cloud Run veya BigQuery) ücretsiz katman sınırlarının ötesinde etkin olarak kullanırsanız yalnızca Google Cloud ücretlerine tabi olursunuz.

5. OAuth 2.0 kimlik doğrulama yapılandırması

Google Ads API, isteklerin kimliğini doğrulamak ve istekleri yetkilendirmek için OAuth 2.0'ı kullanır.

Masaüstü uygulaması akışıyla ilgili adımlar

1. Google Cloud projenizde API'ler ve Hizmetler > OAuth kullanıcı rızası ekranı'na gidip kullanıcı rızası ekranını yapılandırın. Yetkilendirme sırasında erişim hatalarını önlemek için uygulama Test durumundayken e-posta adresinizi Test kullanıcıları bölümüne ekleyin.
2. API'ler ve Hizmetler > Kimlik bilgileri'ne gidin.
3. Kimlik bilgileri oluştur > OAuth istemci kimliği'ni tıklayın.
4. Uygulama türünü Masaüstü uygulaması olarak seçin.
5. Oluştur'u tıklayın, ardından OAuth kimlik bilgileri dosyasını client_secret.json olarak indirin (veya Client ID ve Client Secret değerlerini kopyalayın).

Yenileme jetonu oluşturma

İstemci kimliğinizi ve istemci gizli anahtarınızı aldıktan sonra bir yenileme jetonu oluşturmanız gerekir. Bu işlemi Google OAuth 2.0 Playground'u veya bir istemci kitaplığı komut dosyası kullanarak yapabilirsiniz.

A yöntemi: Google OAuth 2.0 Playground'u kullanma

1. Google OAuth 2.0 Playground'a gidin.
2. Sağ üst köşedeki dişli simgesini (OAuth 2.0 yapılandırması) tıklayın.
3. Kendi OAuth kimlik bilgilerinizi kullanın kutusunu işaretleyin.
4. OAuth2 Client ID ve Client Secret değerlerinizi girip Kapat'ı tıklayın.
5. Soldaki 1. adımda (API'leri seçin ve yetkilendirin), "Kendi kapsamlarınızı girin" alanına Google Ads API kapsamını girin: https://www.googleapis.com/auth/adwords
6. API'leri yetkilendir'i tıklayın. İstendiğinde Google Ads yönetici hesabınıza (veya test hesabınıza) erişimi olan Google Hesabı ile oturum açın.
7. Kullanıcı rızası ekranında Devam'ı tıklayın.
8. 2. adımda (Jetonlar için yetkilendirme kodu değiş tokuşu yap) mavi renkli Jetonlar için yetkilendirme kodu değiş tokuşu yap düğmesini tıklayın.
9. Refresh token ve Access token, yanıt panelinde gösterilir. Refresh token değerini kopyalayıp kaydedin.

2. yöntem: İstemci kitaplığı komut dosyası kullanma (Python örneği)

Resmi Python istemci kitaplığı, kimlik bilgileri oluşturmak için yerleşik bir yardımcı komut dosyası sağlar. Alternatif olarak, client_secret.json dosyanızı Google Cloud Console'dan indirebilir ve aşağıdaki bağımsız Python komut dosyasını çalıştırabilirsiniz:

1. Gerekli OAuth kitaplığını yükleyin:

pip install google-auth-oauthlib

1. generate_refresh_token.py ile aynı dizinde client_secret.json adlı bir komut dosyası oluşturun ve uygulayın:

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. İstemci kitaplığı ve kimlik bilgilerinin ayarlanması

Google, kimlik doğrulama, serileştirme ve gRPC uç noktalarıyla iletişimi yöneten resmi olarak desteklenen istemci kitaplıkları sağlar.

Desteklenen diller

• Python: pip install google-ads
• Java: Maven veya Gradle üzerinden kullanılabilir.
• 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

Yapılandırma dosyası (google-ads.yaml)

Kimlik bilgilerinizi içeren bir yapılandırma dosyası oluşturun. Varsayılan olarak, istemci kitaplığının başlatma yöntemi (ör. GoogleAdsClient.load_from_storage()), google-ads.yaml öğesini iki konumda otomatik olarak arar:

1. Komut dosyanızın çalıştırıldığı mevcut çalışma dizini.
2. Kullanıcı ana dizininiz (Linux/macOS'te ~ veya Windows'da %HOMEPATH%).

Dosyayı özel bir konumda saklarsanız yolu başlatma yöntemine açıkça iletebilirsiniz (ör. 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. İlk API çağrınızı yapma

İlk katılım ayarlarınızı doğrulamak için mevcut kampanyaları test hesabınızdan getiren bir hızlı başlangıç komut dosyası çalıştırın.

Örnek Python komut dosyası (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. En iyi uygulamalar ve kaynaklar

• Günlüğe kaydetme: Google'dan destek isterken gerekli olan istek ve yanıt kimliklerini (request-id) yakalamak için istemci kitaplığınızda ayrıntılı günlüğe kaydetmeyi etkinleştirin.
• Hata İşleme: GoogleAdsException için etkili hata işleme uygulayın. Özellikle sıklık sınırlarını yönetin (RESOURCE_TEMPORARILY_EXHAUSTED).
• Resmi Belgeler: Google Ads API Geliştirici Belgeleri
• İstemci Kitaplıkları ve Kod Örnekleri: GitHub Google Ads Depoları