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 yer almaktadır.

Ö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 geliştirici jetonuna (test hesabı erişimi yeterlidir) ve en az bir müşteri hesabı içeren bir Google Ads yönetici hesabına ihtiyacınız vardır.

Ortam değişkenleri

Hesap kimlik 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şturmayla ilgili talimatlar yer alır.

API_VERSION="20"
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 örneklerin bazıları önceden var olan bütçelerde veya kampanyalarda çalışır. Bu örneklerle kullanmak üzere mevcut nesnelerin kimlikleri varsa bunları gösterildiği gibi girin.

BUDGET_ID=BUDGET_ID
CAMPAIGN_ID=CAMPAIGN_ID

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

Ara

Sorgu Yemek Kitabı kılavuzunda, bazı varsayılan Google Ads ekranlarına karşılık gelen ve bu kılavuzda kullanılan aynı ortam değişkenleriyle çalışan birçok raporlama örneği yer alır. Etkileşimli sorgu oluşturma aracımız da özel sorguları etkileşimli olarak oluşturmak için harika bir kaynaktır.

Sayfalara ayrılmış

search yöntemi, 10.000 öğelik sabit sayfa boyutuyla birlikte sayfalara ayırma özelliğini kullanır ve query ile birlikte bir page_token belirtilir.

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'

### 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ştirir

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

Oluşturur

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

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

BUDGET_ID=BUDGET_ID

Diğer kaynaklara başvuran kaynaklar bunu kaynak adı ile yapar. Aşağıdaki örnekte oluşturulan kampanya, dize değerli kaynak adıyla campaignBudget olarak adlandırılıyor.

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, istekte hangi JSON özelliklerinin bulunması gerektiğini belirten ve virgülle ayrılmış bir liste olan updateMask alanı gerekir. Bu alan, 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 "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 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 hepsi geçerliyse başarılı olur.

Bir sonraki örnekte mevcut bir kampanya kullanılmaktadır. Oluşturur örneği çıktısından kopyalayıp yapıştırabilirsiniz.

CAMPAIGN_ID=CAMPAIGN_ID

Aşağıdaki istek iki işlem içeriyor. İlk deneme, sağlanan kampanyanın teklif stratejisini değiştirmeye çalışır. İkincisi ise geçersiz kimliğe sahip bir kampanyayı kaldırmaya çalışır. İkinci işlem hata verdiğinden (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ürlerde birçok işlem gönderebilirsiniz. Hiçbir işlem başarısız olmazsa işlemlerin tümü başarılı olur. Tek bir işlem başarısız olursa işlemlerin tümü 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. Birbirini izleyen her işlem, bir önceki işleme bağlıdır. Bir işlem başarısız olursa tüm işlemler 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ındaki 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şturabilir, erişilebilen 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ı 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

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 "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, dolguyla birlikte standart Base64 kodlaması kullanılarak dize olarak kodlanır. Doldurma ile veya doldurma olmadan standart ya da URL güvenli Base64 kodlaması kabul edilir.

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

base64 komut satırı yardımcı programını (GNU temel yardımcı programlarının bir parçası) kullanarak 1 piksellik bir GIF resmini kodlayın.

base64 1pixel.gif

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

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

curl

GAQL

Değiştirir

Oluşturur

Güncellemeler

Kaldırılanlar

Kısmi hatalar

Gruplandırılmış işlemler

Hesap yönetimi

Hesap oluşturma

Erişilebilen hesapları listeleme

İkili öğeleri yükleme

Örnekler