Bu kılavuz, REST uç noktalarını istemci kitaplığı kullanmadan doğrudan çağırmayla ilgili örnekler içerir.
Ön koşullar
Aşağıdaki tüm örneklerin, curl komutu kullanılarak bir bash kabuğu içine kopyalanıp yapıştırılması amaçlanmıştır.
Ayrıca geliştirici jetonunuza sahip olmanız, test hesabına erişiminizin olması ve en az bir müşteri hesabı içeren bir Google Ads yönetici hesabınızın olması gerekir.
Ortam değişkenleri
Hesap kimlik bilgilerini ve kimliklerini aşağıya girin. Ardından, gelecek örneklerde kullanılan ortam değişkenlerini yapılandırmak için bunları terminalinize kopyalayıp yapıştırın. Yetkilendirme kılavuzu, OAuth 2.0 erişim jetonu oluşturmayla ilgili talimatları içerir.
API_VERSION="16"
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ı mevcut bütçeler veya kampanyalarda çalışır. Bu örneklerle kullanabileceğiniz mevcut nesnelerin kimlikleriniz varsa bunları aşağıya girin.
BUDGET_ID=BUDGET_ID
CAMPAIGN_ID=CAMPAIGN_ID
Aksi takdirde, iki Değişim - Örnek oluşturur seçeneği yeni bir bütçe ve kampanya oluşturur.
Arama
Sorgu Kılavuzu kılavuzu, bazı varsayılan Google Ads ekranlarına karşılık gelen ve bu kılavuzda kullanılan ortam değişkenleriyle çalışan birçok raporlama örneği içerir. Etkileşimli sorgu oluşturma aracımız etkileşimli olarak özel sorgular oluşturmak için de harika bir kaynaktır.
Sayfalandırılmış
search
yöntemi, query
ile birlikte belirtilen düzenlenebilir pageSize
parametresiyle sayfalandırmayı 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 '{ "pageSize": 10, "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
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ıtla akışını sağladığından 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
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şiklikler
operations
dizisi doldurularak tek bir JSON istek gövdesinde birden fazla değiştirme işlemi (create
, update
veya remove
) gönderilebilir.
Oluşturulanlar
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çesine ait BUDGET_ID
kullanılıyor. Ö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ına göre bir campaignBudget
'a atıfta 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üncelleyin. Bir sonraki örnekte mevcut bir kampanya kullanılmaktadır. Önceki adımın sonucundan kopyalayıp yapıştırabilirsiniz.
CAMPAIGN_ID=CAMPAIGN_ID
Tüm güncellemeler için updateMask
alanı gerekir. İstekte yer alacak JSON özelliklerinin virgülle ayrılmış listesi olan ve güncelleme olarak uygulanmalıdır. updateMask
öğesinde listelenen ancak istek gövdesinde bulunmayan özellikler bir nesnede temizlenir. updateMask
öğesinde listelenmeyen ancak istek gövdesinde bulunan özellikler yok sayı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ı remove
işlemi olarak belirtilerek 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
ise başarılı işlemler gerçekleştirilir ve geçersiz işlemler hata döndürür. false
ise istekteki tüm işlemler, yalnızca hepsinin geçerli olması durumunda başarılı olur.
Bir sonraki örnekte mevcut bir kampanya kullanılmaktadır. Creates örnek çıktısından kopyalayıp yapıştırabilirsiniz.
CAMPAIGN_ID=CAMPAIGN_ID
Aşağıdaki istek iki işlem içeriyor. İlkinde sağlanan kampanyanın teklif stratejisini değiştirmeye, sonraki deneme ise geçersiz kimliğe sahip bir kampanyayı kaldırmaya çalışır. İkinci işlem hatayla sonuçlandığından (kampanya kimliği geçersiz) ve partialFailure
false
değerine 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 çok kaynak türüne sahip işlem gruplarının gönderilmesini destekler. Grup olarak gerçekleştirilmesi gereken bir işlem dizisini zincirlemek için farklı türde birçok işlem gönderebilirsiniz.
Hiçbir işlem başarısız olursa işlem grubu başarılı olur veya tek bir işlem başarısız olursa işlem grubu başarısız olur.
Bu örnekte, kampanya bütçesi, kampanya, reklam grubu ve reklamın tek bir işlem grubu olarak birlikte oluşturulması gösterilmektedir. Arka arkaya gerçekleşen her işlem bir önceki işleme bağlıdır. Biri başarısız olursa tüm işlem grubu başarısız olur.
Negatif tam sayılar (-1
, -2
, -3
) kaynak adlarında yer tutucu olarak kullanılır ve çalışma sırasında işlem sırasından sonuçlarla 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ının 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 yönelik basit bir GET
isteği kullanın. Bu istekte yönetici veya müşteri hesabı kimliği 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 varlıklarını yükleme
assets:mutate
yöntemi, Öğeleri yüklemek ve yönetmek için kullanılır. Resim gibi ikili veriler, dolgulu standart base64 kodlaması kullanılarak dize olarak kodlanır. Dolgulu veya dolgusuz, standart ya da URL için güvenli base64 kodlaması kabul edilir.
Bu örnekte, örneği kısa ve öz tutmak için 1 piksellik bir GIF kodlanmıştır. Pratikte data
yükleri çok daha büyüktür.
1 piksel GIF resmi 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' } } } ] }"