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

Diğer yöntemler

Deneyin.