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' } } } ] }"