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ılavuzda, istemci kitaplığı kullanılmadan REST uç noktalarının doğrudan çağrılmasıyla ilgili örnekler verilmiştir.

Ön koşullar

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

Ayrıca bir geliştirici jetonuna (test hesabı erişimi yeterlidir) ve en az bir müşteri hesabı içeren bir Google Ads yönetici hesabına da ihtiyacınız vardır.

Ortam değişkenleri

Aşağıdaki hesap kimlik bilgilerini ve kimlikleri 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ılavuzunda OAuth 2.0 erişim jetonu oluşturmayla ilgili talimatlar sağlanmaktadır.

API_VERSION="19"
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 oluşturulmuş bütçeler veya kampanyalarda işe yarar. Bu örneklerle kullanılacak mevcut nesnelerin kimliklerini aşağıda girin.

BUDGET_ID=BUDGET_ID
CAMPAIGN_ID=CAMPAIGN_ID

Aksi takdirde, iki Mutates - Creates örnekleri yeni bir bütçe ve kampanya oluşturur.

Ara

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 birçok raporlama örneği içerir. Etkileşimli sorgu oluşturucu aracımız, özel sorguları etkileşimli olarak oluşturmak için de mükemmel bir kaynaktır.

Sayfalara ayrılmış

search yönteminde, 10.000 öğe sabit sayfa boyutu ve query ile birlikte belirtilen bir page_token ile sayfalandırma kullanılı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

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ı tek bir yanıtta yayınlar. 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

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şiklik

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

Oluşturur

Bu örnekte, tek bir istekte iki paylaşılan kampanya bütçesi oluşturulmaktadır.

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 kullanılmaktadır. Önceki adımın çıktısını kopyalayıp yapıştırabilirsiniz.

BUDGET_ID=BUDGET_ID

Diğer kaynaklara atıfta bulunan kaynaklar, kaynak adı ile bunu yapar. Aşağıda oluşturulan kampanya, dize değerli kaynak adıyla bir campaignBudget'yi ifade eder.

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. Sonraki örnekte mevcut bir kampanya kullanılmaktadır. Önceki adımın çıktısı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 bulunması gerektiğini belirten ve güncelleme olarak uygulanması gereken, virgülle ayrılmış bir listetir. updateMask içinde listelenen ancak istek gövdesinde bulunmayan özellikler bir nesnede 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ı 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 varsa 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 tüm işlemler geçerliyse başarılı olur.

Sonraki örnekte mevcut bir kampanya kullanılmaktadır. Oluşturur örneğindeki çıkışı kopyalayıp yapıştırabilirsiniz.

CAMPAIGN_ID=CAMPAIGN_ID

Aşağıdaki istek iki işlem içerir. İlki, sağlanan kampanyanın teklif stratejisini değiştirmeyi, sonraki ise geçersiz kimlikli bir kampanyayı kaldırmayı dener. İkinci işlem hatayla sonuçlandığından (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ü içeren işlem gruplarının gönderilmesini destekler. Grup olarak gerçekleştirilmesi gereken bir işlem dizisini birbirine bağlamak için farklı türde birçok işlem gönderebilirsiniz. Hiçbir işlem başarısız olmazsa işlem grubu başarılı olur. Bir işlem başarısız olursa tüm işlemler başarısız olur.

Bu örnekte, tek bir işlem grubu olarak kampanya bütçesi, kampanya, reklam grubu ve reklamın nasıl oluşturulacağı gösterilmektedir. Ardışık her işlem öncekine bağlıdır. Bir işlem başarısız olursa tüm işlem grubu başarısız olur.

Kaynak adlarında yer tutucu olarak negatif tam sayılar (-1, -2, -3) kullanılır ve çalışma zamanında işlem dizisinden elde edilen 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'de müşteri hesabı kimliği yerine yönetici hesabı kimliğinin kullanıldığını 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şilebilen 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 gönderin. 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 öğeleri yükleme

assets:mutate yöntemi, öğeleri yüklemek ve yönetmek için kullanılır. Resim gibi ikili veriler, dolgu içeren standart Base64 kodlaması kullanılarak dize olarak kodlanır. Dolgu içerse veya içermese standart ya da URL için güvenli base64 kodlaması kabul edilir.

Bu örnekte, örneği kısa tutmak için 1 piksel GIF kodlanır. Pratikte data yükü ç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ıdır) kullanın.

base64 1pixel.gif

Base64 kodlu değer, 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.