Google, içerikleri tercih ettiğiniz dile çevirmek için yapay zeka teknolojisini kullanır. Yapay zeka çevirilerinde hata olabilir.

Örnekler

Bu kılavuzda, istemci kitaplığı kullanılmadan doğrudan REST uç noktalarının çağrılmasına dair örnekler yer almaktadır.

Daha ayrıntılı kod örnekleri için REST kod örnekleri GitHub deposuna göz atın.

Her API yönteminin istek ve yanıt gövdelerini görüntülemek için belirli hizmet uç noktalarıyla ilgili referans belgelerine bakın.

Örneğin, GoogleAdsService.Search için referans sayfası, Search yönteminin istek ve yanıt gövdelerini gösterir.

Ön koşullar

Burada gösterilen tüm örnekler, curl komutu kullanılarak bir bash kabuğuna kopyalanıp yapıştırılmak üzere tasarlanmıştır.

Ayrıca bir Google Cloud projeniz (test hesabı erişimi yeterlidir) ve en az bir müşteri hesabı içeren bir Google Ads yönetici hesabınız olmalıdır.

Ortam değişkenleri

Hesap giriş bilgilerini ve kimlikleri gösterildiği gibi girin, ardından sonraki örneklerde kullanılan ortam değişkenlerini yapılandırmak için terminalinize kopyalayıp yapıştırın. Yetkilendirme kılavuzunda, OAuth 2.0 erişim jetonu oluşturma talimatları yer alır.

API_VERSION="26"
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 kampanyalar üzerinde çalışır. Bu örneklerde kullanabileceğiniz mevcut nesnelerin kimlikleri varsa bunları gösterildiği gibi girin.

BUDGET_ID=BUDGET_ID
CAMPAIGN_ID=CAMPAIGN_ID

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

Ara

Sorgu Yemek Kitabı kılavuzu, varsayılan Google Ads ekranlarından bazıları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 da özel sorguları etkileşimli olarak oluşturmak için mükemmel bir kaynaktır.

Sayfalara ayrılmış

search yöntemi, 10.000 öğelik sabit sayfa boyutu ve query ile birlikte belirtilen bir page_token ile sayfalama 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 "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 "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 mutasyon işlemi (create, update veya remove) gönderilebilir.

Oluşturur

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

curl -f --request POST "https://googleads.googleapis.com/v${API_VERSION}/customers/${CUSTOMER_ID}/campaignBudgets:mutate" \
--header "Content-Type: application/json" \
--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,
    }
  }
]
}"

Bir sonraki örnekte mevcut bir kampanya bütçesinin BUDGET_ID değeri kullanılır. Bu değeri önceki adımın çıkışından kopyalayıp yapıştırabilirsiniz.

BUDGET_ID=BUDGET_ID

Diğer kaynaklara referans veren kaynaklar, bunu kaynak adı ile yapar. Aşağıdaki örnekte oluşturulan kampanya, dize değerli kaynak adıyla bir campaignBudget öğesine başvurur.

curl -f --request POST "https://googleads.googleapis.com/v${API_VERSION}/customers/${CUSTOMER_ID}/campaigns:mutate" \
--header "Content-Type: application/json" \
--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 çıkışından kopyalayıp yapıştırabilirsiniz.

CAMPAIGN_ID=CAMPAIGN_ID

Tüm güncellemeler için bir updateMask alanı gerekir. Bu alan, istekte bulunması gereken JSON özelliklerinin virgülle ayrılmış bir listesidir ve güncelleme olarak uygulanmalıdır. 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 "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 "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 geçerli oldukları takdirde başarılı olur.

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

CAMPAIGN_ID=CAMPAIGN_ID

Aşağıdaki istek iki işlem içerir. İlk işlem, sağlanan kampanyanın teklif stratejisini değiştirmeye çalışır. Sonraki işlem ise geçersiz kimliğe sahip bir kampanyayı kaldırmaya çalışır. İkinci işlem hatayla sonuçlandığı (kampanya kimliği geçersiz) ve partialFailure, false olarak ayarlandığı için 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 "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ürlerde birçok işlem gönderebilirsiniz. Hiçbir işlem başarısız olmazsa işlem grubu başarılı olur. Tek bir işlem bile başarısız olursa tüm işlemler başarısız olur.

Bu örnekte, kampanya bütçesi, kampanya, reklam grubu ve reklamın tek bir işlem grubu olarak birlikte nasıl oluşturulacağı gösterilmektedir. Her bir 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 zamanında işlem sırasından 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 "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şturabilir, erişilebilir hesapları listeleyebilir ve ikili öğeler yükleyebilirsiniz.

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 "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

Belirli bir 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 "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, dolgulu standart Base64 kodlaması kullanılarak dize olarak kodlanır. Dolgu içeren veya içermeyen standart ya da URL için güvenli Base64 kodlaması kabul edilir.

Bu örnekte, kısa olması için 1 piksellik bir GIF kodlanmıştır. Uygulamada, data yükleri çok daha büyüktür.

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

Yaygın görülen hatalar

Deneyin.

Örnekler Koleksiyonlar ile düzeninizi koruyun İçeriği tercihlerinize göre kaydedin ve kategorilere ayırın.

Ön koşullar

Ortam değişkenleri

İsteğe bağlı ek nesne kimlikleri

Ara

Sayfalara ayrılmış

curl

GAQL

Canlı Yayın

curl

GAQL

Değişiklikler

Oluşturur

Güncellemeler

Kaldırılanlar

Kısmi hatalar

Gruplandırılmış işlemler

Hesap yönetimi

Hesap oluşturma

Erişilebilir hesapları listeleme

İkili öğeleri yükleme

Örnekler