Başlarken

Bu kılavuzda, Google Ads API .NET kitaplığını kullanmaya başlama hakkında kısa bir genel bakış sunulmaktadır.

Kurulum

İstemci kitaplığı ikili dosyaları NuGet kullanılarak dağıtılır. İstemci kitaplığını kullanmak için projenizdeki Google.Ads.GoogleAds paketine bir NuGet referansı ekleyin.

Yetkilendirme kurulumu

API çağrılarınızı yetkilendirmek için kitaplığa istemci kimliğinizi, istemci gizli anahtarınızı, yenileme jetonunuzu ve geliştirici jetonunuzu belirtmeniz gerekir.

Kimlik bilgisi oluşturmanız gerekiyorsa

Zaten kimlik bilgileriniz varsa

  • GoogleAdsApi düğümünü ve configSections düğümünün altındaki GoogleAdsApi bölümünü GitHub'daki App.config dosyasından App.config / Web.config dosyanıza kopyalayın. Paketi yüklemek için NuGet'i kullandıysanız bu düğümler App.config / Web.config dosyanıza otomatik olarak eklenir.
  • Geliştirici jetonunu, istemci kimliğini, istemci sırrını ve yenileme jetonunu uygulamanızın App.config / Web.config bölümüne ekleyin.

GitHub'a dahil edilen App.config dosyasıyla ilgili ayrıntılı dokümanlar mevcuttur. Daha fazla bilgi edinmek ve istemci kitaplığını yapılandırmayla ilgili alternatif yöntemler (ör. ortam değişkenleri) kullanmak için Yapılandırma kılavuzuna da bakabilirsiniz.

API çağrısı yapma

İstemci kitaplığının temel kullanımı aşağıdaki gibidir:

// Create a Google Ads client.
GoogleAdsClient client = new GoogleAdsClient();

// Create the required service.
CampaignServiceClient campaignService =
    client.GetService(Services.V18.CampaignService);

// Make more calls to service class.

GoogleAdsClient örneği oluşturma

Google Ads API .NET kitaplığındaki en önemli sınıf GoogleAdsClient sınıfıdır. API çağrıları yapmak için kullanılabilecek önceden yapılandırılmış bir hizmet sınıfı oluşturmanıza olanak tanır. GoogleAdsClient, uygulamanızın App.config / Web.config bölümünde belirtilen ayarları kullanarak bir kullanıcı nesnesi oluşturan varsayılan bir kurucu sağlar. Yapılandırma seçenekleri için yapılandırma kılavuzuna bakın.

// Create a new GoogleAdsClient with the App.config settings.
GoogleAdsClient user = new GoogleAdsClient();

Hizmet oluştur

GoogleAdsClient, Ads hizmeti oluşturmak için kullanılabilecek bir GetService yöntemi sağlar.

CampaignServiceClient campaignService = client.GetService(Services.V18.CampaignService);
// Now make calls to CampaignService.

Desteklenen tüm API sürümlerini ve hizmetlerini listeleyen bir Services sınıfı sağlarız. GetService yöntemi, hizmeti oluştururken bu listeleme nesnelerini bağımsız değişken olarak kabul eder. Örneğin, Google Ads API'nin V18 sürümü için CampaignServiceClient örneği oluşturmak üzere önceki örnekte gösterildiği gibi GoogleAdsClient.GetService yöntemini Services.V18.CampaignService bağımsız değişkeni ile çağırmanız gerekir.

Mesaj dizisi güvenliği

Bir GoogleAdsClient örneğini birden fazla iş parçacığı arasında paylaşmak güvenli değildir. Çünkü bir iş parçacığındaki bir örnekte yaptığınız yapılandırma değişiklikleri, diğer iş parçacıklarında oluşturduğunuz hizmetleri etkileyebilir. GoogleAdsClient örneğinden yeni hizmet örnekleri elde etme ve birden fazla hizmete paralel olarak çağrı yapma gibi işlemler, iş parçacığı açısından güvenlidir.

Çok iş parçacıklı bir uygulama aşağıdaki gibi görünür:

GoogleAdsClient client1 = new GoogleAdsClient();
GoogleAdsClient client2 = new GoogleAdsClient();

Thread userThread1 = new Thread(addAdGroups);
Thread userThread2 = new Thread(addAdGroups);

userThread1.start(client1);
userThread2.start(client2);

userThread1.join();
userThread2.join();

public void addAdGroups(object data) {
  GoogleAdsClient client = (GoogleAdsClient) data;
  // Do more operations here.
  ...
}

.NET Framework uygulamalarında donmalardan kaçının

Senkronize yöntemler, .NET Framework uygulamalarınızın bazılarının donmasına neden olabilir. Yaygın bir örnek, WinForm uygulamasının bir etkinlik işleyici yönteminden API çağrıları yapmaktır.

Bu sorunu gidermenin iki yolu vardır:

  1. Eski Grpc kitaplığını kullanın.

    GoogleAdsConfig öğesinin UseGrpcCore özelliğini, varsayılan Grpc.Net.Client kitaplığı yerine eski Grpc.Core kitaplığını kullanacak şekilde ayarlayabilirsiniz. Bu yöntem, .NET Framework uygulamaları üzerinde kapsamlı bir şekilde test edilmediğinden sorunu çözmeyebilir. Aşağıda örnek bir snippet verilmiştir:

    GoogleAdsConfig config = new GoogleAdsConfig();
config.UseGrpcCore = true;
GoogleAdsClient client = new GoogleAdsClient(config);

  2. Eşzamansız yöntemler kullanın.

    Donmayı önlemek için eşzamansız yöntemler kullanabilirsiniz. Aşağıda bazı örnekler verilmiştir:

    SearchStream

    SearchStream() çağrısı yapılır ve sonuçlar liste görünümünde doldurulur.

    private async void button1_Click(object sender, EventArgs e)
{
// Get the GoogleAdsService.
GoogleAdsServiceClient googleAdsService = client.GetService(
    Services.V18.GoogleAdsService);
 
// Create a query that will retrieve all campaigns.
string query = @"SELECT
                campaign.id,
                campaign.name,
                campaign.network_settings.target_content_network
            FROM campaign
            ORDER BY campaign.id";
 
List items = new List();
Task t =  googleAdsService.SearchStreamAsync(customerId.ToString(), query,
    delegate (SearchGoogleAdsStreamResponse resp)
    {
        foreach (GoogleAdsRow googleAdsRow in resp.Results)
        {
            ListViewItem item = new ListViewItem();
            item.Text = googleAdsRow.Campaign.Id.ToString();
            item.SubItems.Add(googleAdsRow.Campaign.Name);
            items.Add(item);
        }
    }
);
await t;
listView1.Items.AddRange(items.ToArray());
}

    Kampanya Bütçesi

    CampaignBudget çağrısı oluşturulur ve yeni bütçenin kaynak adı MessageBox uyarısı kullanılarak gösterilir.

    private async void button2_Click(object sender, EventArgs e)
{
// Get the BudgetService.
CampaignBudgetServiceClient budgetService = client.GetService(
    Services.V18.CampaignBudgetService);
 
// Create the campaign budget.
CampaignBudget budget = new CampaignBudget()
{
    Name = "Interplanetary Cruise Budget #" + ExampleUtilities.GetRandomString(),
    DeliveryMethod = BudgetDeliveryMethod.Standard,
    AmountMicros = 500000
};
 
// Create the operation.
CampaignBudgetOperation budgetOperation = new CampaignBudgetOperation()
{
    Create = budget
};
 
// Create the campaign budget.
Task t = budgetService.MutateCampaignBudgetsAsync(
    customerId.ToString(), new CampaignBudgetOperation[] { budgetOperation });
 
await t;
MutateCampaignBudgetsResponse response = t.Result;
MessageBox.Show(response.Results[0].ResourceName);
}

Hata işleme

Her API çağrısı başarılı olmaz. API çağrılarınız herhangi bir nedenle başarısız olursa sunucu hata verebilir. API hatalarını yakalamak ve uygun şekilde ele almak önemlidir.

API hatası oluştuğunda bir GoogleAdsException örneği oluşturulur. Bu raporda, sorunun ne olduğunu anlamanıza yardımcı olacak ayrıntılar yer alır:

// Get the CampaignService.
CampaignServiceClient campaignService = client.GetService(Services.V18.CampaignService);

// Create a campaign for update.
Campaign campaignToUpdate = new Campaign()
{
    ResourceName = ResourceNames.Campaign(customerId, campaignId),
    // More fields to update.
    // ...
};

// Create the operation.
CampaignOperation operation = new CampaignOperation()
{
    Update = campaignToUpdate,
    UpdateMask = FieldMasks.AllSetFieldsOf(campaignToUpdate)
};

try
{
    // Update the campaign.
    MutateCampaignsResponse response = campaignService.MutateCampaigns(
        customerId.ToString(), new CampaignOperation[] { operation });

    // Display the results.
    // ...
}
catch (GoogleAdsException e)
{
    Console.WriteLine("Failure:");
    Console.WriteLine($"Message: {e.Message}");

    // Can examine to get more error details.
    Console.WriteLine($"Failure: {e.Failure}");

    // Can be shared with Google for further troubleshooting.
    Console.WriteLine($"Request ID: {e.RequestId}");
}