Dikkat: API'nin REST arayüzüyle ilgili dokümanları görüntülüyorsunuz. Resmi istemci kitaplıklarımızın çoğu gTB kullanır. Ayrıntılar için REST Tanıtımı'nı inceleyin.

Bu sayfa, Cloud Translation API ile çevrilmiştir.

Örnekler

Bu kılavuz, istemci kitaplığı kullanılmadan REST uç noktalarını doğrudan çağırma örnekleri içerir.

Ön koşullar

Aşağıdaki tüm örnekler, curl komutu kullanılarak kopyalanıp bir bash kabuğuna yapıştırılır.

Ayrıca, bir geliştirici jetonunuz, test hesabı erişimine ve en az bir müşteri hesabı içeren bir Google Ads yönetici hesabına ihtiyacınız vardır.

Ortam değişkenleri

Hesap kimlik bilgilerini ve kimliklerini aşağıya girin. Ardından, sonraki örneklerde kullanılan ortam değişkenlerini yapılandırmak için kopyalayıp terminalinize yapıştırın. Yetkilendirme kılavuzu, OAuth 2.0 erişim jetonu oluşturma talimatlarını sağlar.

API_VERSION="17"
DEVELOPER_TOKEN="DEVELOPER_TOKEN"
OAUTH2_ACCESS_TOKEN="OAUTH_ACCESS_TOKEN"
MANAGER_CUSTOMER_ID="MANAGER_CUSTOMER_ID"
CUSTOMER_ID="CUSTOMER_ID"

İsteğe bağlı ek nesne kimlikleri

Aşağıdaki örneklerden bazıları önceden var olan bütçeler veya kampanyalarda işe yarar. Bu örneklerle kullanılacak mevcut nesnelerin kimlikleriniz varsa bunları aşağıya girin.

BUDGET_ID=BUDGET_ID
CAMPAIGN_ID=CAMPAIGN_ID

Aksi takdirde, iki Değişiklik - Örnek oluşturur seçeneği yeni bir bütçe ve kampanya oluşturur.

Arama

Sorgu Tarif Defteri kılavuzu, varsayılan Google Ads ekranlarından bazılarına karşılık gelen ve bu kılavuzda kullanılan aynı ortam değişkenleriyle çalışan çok sayıda raporlama örneği içerir. Etkileşimli sorgu oluşturucu aracımız, etkileşimli özel sorgular oluşturmak için de mükemmel bir kaynaktır.

Sayfalandırılmış

search yöntemi, 10.000 öğelik sabit sayfa boyutu ve query ile birlikte bir page_token öğesi ile sayfalara ayırma kullanır.

cURL

curl -f --request POST "https://googleads.googleapis.com/v${API_VERSION}/customers/${CUSTOMER_ID}/googleAds:search" \
--header "Content-Type: application/json" \
--header "developer-token: ${DEVELOPER_TOKEN}" \
--header "login-customer-id: ${MANAGER_CUSTOMER_ID}" \
--header "Authorization: Bearer ${OAUTH2_ACCESS_TOKEN}" \
--data '{
"query": "
  SELECT campaign.name,
    campaign_budget.amount_micros,
    campaign.status,
    campaign.optimization_score,
    campaign.advertising_channel_type,
    metrics.clicks,
    metrics.impressions,
    metrics.ctr,
    metrics.average_cpc,
    metrics.cost_micros,
    campaign.bidding_strategy_type
  FROM campaign
  WHERE segments.date DURING LAST_7_DAYS
    AND campaign.status != 'REMOVED'
",
"page_token":"${PAGE_TOKEN}"
}'

GAQL (GAQL)

SELECT campaign.name,
  campaign_budget.amount_micros,
  campaign.status,
  campaign.optimization_score,
  campaign.advertising_channel_type,
  metrics.clicks,
  metrics.impressions,
  metrics.ctr,
  metrics.average_cpc,
  metrics.cost_micros,
  campaign.bidding_strategy_type
FROM campaign
WHERE segments.date DURING LAST_7_DAYS
  AND campaign.status != 'REMOVED'

Canlı Yayın

searchStream yöntemi tüm sonuçların tek bir yanıtta akışını sağlar, bu nedenle pageSize alanı desteklenmez.

cURL

curl -f --request POST "https://googleads.googleapis.com/v${API_VERSION}/customers/${CUSTOMER_ID}/googleAds:searchStream" \
--header "Content-Type: application/json" \
--header "developer-token: ${DEVELOPER_TOKEN}" \
--header "login-customer-id: ${MANAGER_CUSTOMER_ID}" \
--header "Authorization: Bearer ${OAUTH2_ACCESS_TOKEN}" \
--data '{
"query": "
  SELECT campaign.name,
    campaign_budget.amount_micros,
    campaign.status,
    campaign.optimization_score,
    campaign.advertising_channel_type,
    metrics.clicks,
    metrics.impressions,
    metrics.ctr,
    metrics.average_cpc,
    metrics.cost_micros,
    campaign.bidding_strategy_type
  FROM campaign
  WHERE segments.date DURING LAST_7_DAYS
    AND campaign.status != 'REMOVED'
"
}'

GAQL (GAQL)

SELECT campaign.name,
  campaign_budget.amount_micros,
  campaign.status,
  campaign.optimization_score,
  campaign.advertising_channel_type,
  metrics.clicks,
  metrics.impressions,
  metrics.ctr,
  metrics.average_cpc,
  metrics.cost_micros,
  campaign.bidding_strategy_type
FROM campaign
WHERE segments.date DURING LAST_7_DAYS
  AND campaign.status != 'REMOVED'

Değişimler

operations dizisi doldurularak tek bir JSON istek gövdesinde birden fazla değişiklik işlemi (create, update veya remove) gönderilebilir.

Oluşturma

Bu örnek, tek bir istekte iki paylaşılan kampanya bütçesi oluşturur.

curl -f --request POST "https://googleads.googleapis.com/v${API_VERSION}/customers/${CUSTOMER_ID}/campaignBudgets:mutate" \
--header "Content-Type: application/json" \
--header "developer-token: ${DEVELOPER_TOKEN}" \
--header "login-customer-id: ${MANAGER_CUSTOMER_ID}" \
--header "Authorization: Bearer ${OAUTH2_ACCESS_TOKEN}" \
--data "{
'operations': [
  {
    'create': {
      'name': 'My Campaign Budget #${RANDOM}',
      'amountMicros': 500000,
    }
  },
  {
    'create': {
      'name': 'My Campaign Budget #${RANDOM}',
      'amountMicros': 500000,
    }
  }
]
}"

Sonraki örnekte, mevcut bir kampanya bütçesinin BUDGET_ID kadarı kullanılmaktadır; önceki adımın çıktısından kopyalayıp yapıştırabilirsiniz.

BUDGET_ID=BUDGET_ID

Diğer kaynaklara referans veren kaynaklar bunu kaynak adıyla yapar. Aşağıda oluşturulan kampanya, dize değerli kaynak adıyla bir campaignBudget öğesine başvuruda bulunuyor.

curl -f --request POST "https://googleads.googleapis.com/v${API_VERSION}/customers/${CUSTOMER_ID}/campaigns:mutate" \
--header "Content-Type: application/json" \
--header "developer-token: ${DEVELOPER_TOKEN}" \
--header "login-customer-id: ${MANAGER_CUSTOMER_ID}" \
--header "Authorization: Bearer ${OAUTH2_ACCESS_TOKEN}" \
--data "{
'operations': [
  {
    'create': {
      'status': 'PAUSED',
      'advertisingChannelType': 'SEARCH',
      'geoTargetTypeSetting': {
        'positiveGeoTargetType': 'PRESENCE_OR_INTEREST',
        'negativeGeoTargetType': 'PRESENCE_OR_INTEREST'
      },
      'name': 'My Search campaign #${RANDOM}',
      'campaignBudget': 'customers/${CUSTOMER_ID}/campaignBudgets/${BUDGET_ID}',
      'targetSpend': {}
    }
  }
]
}"

Güncellemeler

update işlemlerini kullanarak mevcut nesnelerin özelliklerini güncelleme. Sonraki örnekte mevcut bir kampanya kullanılmıştır. Önceki adımın çıkışını kopyalayıp yapıştırabilirsiniz.

CAMPAIGN_ID=CAMPAIGN_ID

Tüm güncellemeler için bir updateMask alanı gerekir. Bu alan, istekte hangi JSON özelliklerinin yer alması gerektiğinin virgülle ayrılmış bir listesidir ve güncelleme olarak uygulanır. updateMask öğesinde listelenen ancak istek gövdesinde bulunmayan özellikler nesne üzerindeki temizlenir. updateMask içinde listelenmeyen ancak istek gövdesinde bulunan özellikler yoksayılır.

curl -f --request POST "https://googleads.googleapis.com/v${API_VERSION}/customers/${CUSTOMER_ID}/campaigns:mutate" \
--header "Content-Type: application/json" \
--header "developer-token: ${DEVELOPER_TOKEN}" \
--header "login-customer-id: ${MANAGER_CUSTOMER_ID}" \
--header "Authorization: Bearer ${OAUTH2_ACCESS_TOKEN}" \
--data "{
'operations': [
  {
    'update': {
      'resourceName': 'customers/${CUSTOMER_ID}/campaigns/${CAMPAIGN_ID}',
      'name': 'A changed campaign name #${RANDOM}',
    },
    'updateMask': 'name'
  }
],
}"

Kaldırılanlar

Nesneler, kaynak adlarının remove işlemi olarak belirtilmesiyle kaldırılır.

curl -f --request POST "https://googleads.googleapis.com/v${API_VERSION}/customers/${CUSTOMER_ID}/campaigns:mutate" \
--header "Content-Type: application/json" \
--header "developer-token: ${DEVELOPER_TOKEN}" \
--header "login-customer-id: ${MANAGER_CUSTOMER_ID}" \
--header "Authorization: Bearer ${OAUTH2_ACCESS_TOKEN}" \
--data "{
'operations': [
  {
    'remove': 'customers/${CUSTOMER_ID}/campaigns/${CAMPAIGN_ID}'
  }
],
}"

Kısmi hatalar

Tek bir istekte birden fazla işlem olduğunda isteğe bağlı olarak partialFailure değerini belirtin. true değerine ayarlanırsa başarılı işlemler gerçekleştirilir ve geçersiz işlemler hata döndürür. false ise istekteki tüm işlemlerin başarılı olması için tümünün geçerli olması gerekir.

Sonraki örnekte, mevcut bir kampanya kullanılmıştır. Oluşturma işlemleri örneği çıkışından kopyalayıp yapıştırabilirsiniz.

CAMPAIGN_ID=CAMPAIGN_ID

Aşağıdaki istek iki işlem içeriyor. İlki, sağlanan kampanyanın teklif stratejisini değiştirmeye çalışıyor. Sonraki adım ise geçersiz kimliğe sahip bir kampanyayı kaldırmaya çalışıyor. İkinci işlem hataya neden olduğundan (kampanya kimliği geçersiz) ve partialFailure, false olarak ayarlandığından ilk işlem de başarısız olur ve mevcut kampanyanın teklif stratejisi güncellenmez.

curl --request POST "https://googleads.googleapis.com/v${API_VERSION}/customers/${CUSTOMER_ID}/campaigns:mutate" \
--header "Content-Type: application/json" \
--header "developer-token: ${DEVELOPER_TOKEN}" \
--header "login-customer-id: ${MANAGER_CUSTOMER_ID}" \
--header "Authorization: Bearer ${OAUTH2_ACCESS_TOKEN}" \
--data "{
'partialFailure': false,
'operations': [
  {
    'update': {
      'resourceName': 'customers/${CUSTOMER_ID}/campaigns/${CAMPAIGN_ID}',
      'manualCpc': {
        'enhancedCpcEnabled': false
      }
    },
    'updateMask': 'manual_cpc.enhanced_cpc_enabled'
  },
  {
    'remove': 'customers/${CUSTOMER_ID}/campaigns/INVALID_CAMPAIGN_ID'
  }
]
}"

Gruplandırılmış işlemler

googleAds:mutate yöntemi, birden fazla kaynak türüyle işlem gruplarının gönderilmesini destekler. Grup olarak yapılması gereken bir dizi işlemi zincirlemek için farklı türlerde birçok işlem gönderebilirsiniz. Hiçbir işlem başarısız olursa işlemler grubu başarılı olur ya da tek bir işlem başarısız olursa tümü başarısız olur.

Bu örnekte, bir kampanya bütçesinin, kampanyanın, reklam grubunun ve reklamın tek bir işlem grubu olarak birlikte oluşturulması gösterilmektedir. Birbirini izleyen her işlem bir öncekine bağlıdır. Biri başarısız olursa işlem grubunun tamamı başarısız olur.

Negatif tam sayılar (-1, -2, -3) kaynak adlarında yer tutucu olarak kullanılır ve çalışma zamanında işlem sırasının sonuçlarıyla dinamik olarak doldurulur.

curl -f --request POST "https://googleads.googleapis.com/v${API_VERSION}/customers/${CUSTOMER_ID}/googleAds:mutate" \
--header "Content-Type: application/json" \
--header "developer-token: ${DEVELOPER_TOKEN}" \
--header "login-customer-id: ${MANAGER_CUSTOMER_ID}" \
--header "Authorization: Bearer ${OAUTH2_ACCESS_TOKEN}" \
--data "{
'mutateOperations': [
  {
    'campaignBudgetOperation': {
      'create': {
        'resourceName': 'customers/${CUSTOMER_ID}/campaignBudgets/-1',
        'name': 'My Campaign Budget #${RANDOM}',
        'deliveryMethod': 'STANDARD',
        'amountMicros': 500000,
        'explicitlyShared': false
      }
    }
  },
  {
    'campaignOperation': {
      'create': {
        'resourceName': 'customers/${CUSTOMER_ID}/campaigns/-2',
        'status': 'PAUSED',
        'advertisingChannelType': 'SEARCH',
        'geoTargetTypeSetting': {
          'positiveGeoTargetType': 'PRESENCE_OR_INTEREST',
          'negativeGeoTargetType': 'PRESENCE_OR_INTEREST'
        },
        'name': 'My Search campaign #${RANDOM}',
        'campaignBudget': 'customers/${CUSTOMER_ID}/campaignBudgets/-1',
        'targetSpend': {}
      }
    }
  },
  {
    'adGroupOperation': {
      'create': {
        'resourceName': 'customers/${CUSTOMER_ID}/adGroups/-3',
        'campaign': 'customers/${CUSTOMER_ID}/campaigns/-2',
        'name': 'My ad group #${RANDOM}',
        'status': 'PAUSED',
        'type': 'SEARCH_STANDARD'
      }
    }
  },
  {
    'adGroupAdOperation': {
      'create': {
        'adGroup': 'customers/${CUSTOMER_ID}/adGroups/-3',
        'status': 'PAUSED',
        'ad': {
          'responsiveSearchAd': {
            'headlines': [
              {
                'pinned_field': 'HEADLINE_1',
                'text': 'An example headline'
              },
              {
                'text': 'Another example headline'
              },
              {
                'text': 'Yet another headline'
              }
            ],
            'descriptions': [
              {
                'text': 'An example description'
              },
              {
                'text': 'Another example description'
              }
            ],
            'path1': 'all-inclusive',
            'path2': 'deals'
          },
          'finalUrls': ['https://www.example.com']
        }
      }
    }
  }
]
}"

Hesap yönetimi

Hesap oluşturma

createCustomerClient yöntemini kullanarak yeni hesaplar oluşturun. URL'nin müşteri hesabı kimliği yerine yönetici hesabı kimliği gerektirdiğini unutmayın. Yönetici hesabı altında yeni bir müşteri hesabı oluşturulur.

curl f --request POST "https://googleads.googleapis.com/v${API_VERSION}/customers/${MANAGER_CUSTOMER_ID}:createCustomerClient" \
--header "Content-Type: application/json" \
--header "developer-token: ${DEVELOPER_TOKEN}" \
--header "login-customer-id: ${MANAGER_CUSTOMER_ID}" \
--header "Authorization: Bearer ${OAUTH2_ACCESS_TOKEN}" \
--data "{
'customerClient': {
  'descriptiveName': 'My Client #${RANDOM}',
  'currencyCode': 'USD',
  'timeZone': 'America/New_York'
}
}"

Erişilebilir hesapları listeleme

Belirtilen OAuth 2.0 erişim jetonuyla erişilebilen Google Ads hesaplarının listesini almak için listAccessibleCustomers yöntemine basit bir GET isteği kullanın. Bu istekte yönetici veya müşteri hesabı kimlikleri kullanılmamalıdır.

curl -f --request GET "https://googleads.googleapis.com/v${API_VERSION}/customers:listAccessibleCustomers" \
--header "Content-Type: application/json" \
--header "developer-token: ${DEVELOPER_TOKEN}" \
--header "Authorization: Bearer ${OAUTH2_ACCESS_TOKEN}" \

İkili program öğelerini yükleme

Öğeleri yüklemek ve yönetmek için assets:mutate yöntemi kullanılır. Resim gibi ikili veriler, dolgulu standart base64 kodlaması kullanan bir dize olarak kodlanır. Dolgulu veya dolgusuz standart ya da URL için güvenli base64 kodlaması kabul edilir.

Bu örnekte, örneğin kısa ve öz olması için 1 piksellik bir GIF kodlanmıştır. Pratikte data yükleri çok daha büyüktür.

1 piksellik GIF resmini kodlamak için base64 komut satırı yardımcı programını (GNU temel yardımcı programlarının bir parçası) kullanın.

base64 1pixel.gif

base64 olarak kodlanmış değer, bir API isteğinde data özelliği olarak belirtilir.

curl -f --request POST "https://googleads.googleapis.com/v${API_VERSION}/customers/${CUSTOMER_ID}/assets:mutate" \
--header "Content-Type: application/json" \
--header "developer-token: ${DEVELOPER_TOKEN}" \
--header "login-customer-id: ${MANAGER_CUSTOMER_ID}" \
--header "Authorization: Bearer ${OAUTH2_ACCESS_TOKEN}" \
--data "{
'operations': [
  {
    'create': {
      'name': 'My image asset #${RANDOM}',
      'type': 'IMAGE',
      'imageAsset': {
        'data': 'R0lGODlhAQABAAAAACH5BAEAAAAALAAAAAABAAEAAAIA'
      }
    }
  }
]
}"

Diğer yöntemler

Deneyin.