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, REST uç noktalarını veya istemci kitaplığını kullanabilirsiniz.

Ön koşullar

Aşağıdaki tüm örnekler kopyalanıp bash etiketi içine yapıştırılmalıdır. shell için curl komutunu kullanın.

Ayrıca, bir geliştirici jetona ve test hesap erişimine izin verilir ve En az bir müşteri hesabı içeren Google Ads yönetici hesabı.

Ortam değişkenleri

Aşağıya hesap kimlik bilgilerini ve kimliklerini girin ve kopyalayıp terminali için. Yetkilendirme kılavuzu, OAuth 2.0 erişim jetonu.

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. Şu durumda: örnekleriyle kullanılacak mevcut nesnelerin kimliklerini görüyorsanız bunları aşağıya girin.

BUDGET_ID=BUDGET_ID
CAMPAIGN_ID=CAMPAIGN_ID

Aksi takdirde, iki Dönüşüm Gerçekleştirme - Örnek oluşturur seçeneği yeni bir bütçe oluşturur ve kampanyayı seçin.

Arama

Sorgu Tarif Defteri kılavuzu birçok raporlama içerir bazı varsayılan Google Ads ekranlarına karşılık gelen ve bu kılavuzda kullanılan ortam değişkenlerinin aynısını kullanın. Etkileşimli sorgusumuz oluşturma aracı etkileşimli özel sorgular oluşturmak için mükemmel bir kaynaktır.

Sayfalandırılmış

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

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, dolayısıyla pageSize alanı desteklenmiyor.

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

Tek seferde birden çok değişiklik işlemi (create, update veya remove) gönderilebilir tek JSON istek gövdesini operations dizisini doldurarak düzenleyebilirsiniz.

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; CANNOT TRANSLATE önceki adımın çıktısından kopyalayıp yapıştırın.

BUDGET_ID=BUDGET_ID

Diğer kaynaklara referans veren kaynaklar kaynak adı. Aşağıda oluşturulan kampanya dize değerli kaynak adıyla bir campaignBudget anlamına gelir.

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 örneğin mevcut bir kampanyayı kullanıyorsa önceki kayıttan kopyalayıp yapıştırarak adımının çıktısı.

CAMPAIGN_ID=CAMPAIGN_ID

Tüm güncellemeler için bir updateMask alanı, istekte bulunması gereken JSON özelliklerini güncelleyin. updateMask kapsamında listelenen ancak istekte bulunmayan özellikler gövdesinin silinmemesidir. Özellikler updateMask içinde listelenmemiş, ancak mevcut dışındaki etiketler 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 çok işlem olduğunda isteğe bağlı olarak belirtin partialFailure 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 başarılı olmaları gerekir.

Bir sonraki örnekte, mevcut bir kampanya kullanılmıştır; kopyalayıp yapıştırarak Oluşturma örnek çıkışı.

CAMPAIGN_ID=CAMPAIGN_ID

Aşağıdaki istek iki işlem içeriyor. İlk deneme, kampanyanın teklif stratejisini etkiler ve sonraki kampanya, kampanyanın bir geçersiz bir kimliğe sahip kampanya. İkinci işlem bir hatayla sonuçlandığından ( kampanya kimliği geçersizdir) ve partialFailure, false olarak ayarlandığı için başarısız olur ve mevcut kampanyanın teklif stratejisi güncellenmedi.

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, değerlendirebiliriz. Web sitenize farklı türlerde birçok işlem gönderebilirsiniz: bir dizi işlem zinciri olduğunu unutmayın. Hiçbir işlem başarısız olursa işlem kümesi başarılı olur veya herhangi bir işlem başarısız olursa bir işlem başarısız olur.

Bu örnekte, bir kampanya bütçesi, kampanya, reklam grubu ve tek bir işlem grubu olarak bir araya getirir. Birbirini takip eden her işlem, bir tane oluşturabilirsiniz. Biri başarısız olursa işlem grubunun tamamı başarısız olur.

Negatif tam sayılar (-1, -2, -3) kaynakta yer tutucu olarak kullanılıyor isimlerini sunar ve dizideki sonuçlarla birlikte çalışma zamanında dinamik olarak doldurulur. anlamına gelir.

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 gerektirir. Yeni bir müşteri yönetici hesabının altında 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

Liste almak için listAccessibleCustomers yöntemine basit bir GET isteği ekleyin Belirtilen OAuth 2.0 erişim jetonuyla erişilebilen Google Ads hesabı sayısı. Yönetici yok veya müşteri hesabı kimlikleri bu istekte kullanılmalı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

Yükleme ve yönetme için assets:mutate yöntemi kullanılır Öğeler. Bir görüntü gibi ikili veriler Dolgulu standart base64 kodlaması kullanan bir dize. Standart veya Dolgulu veya dolgusuz 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ükü çok daha büyüktür.

base64 komut satırı yardımcı programını ( GNU temel yardımcı programları) kullanarak 1 piksellik GIF resmi kodlayabilirsiniz.

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.