Başlayın

Bu kılavuzda, Google Ads API.NET kitaplığını kullanmaya nasıl başlayacağınıza dair kısa bir genel bakış sunulmaktadır.

Döşeme

İstemci kitaplığı ikili programları, 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 istemci kimliğinizi, istemci gizli anahtarınızı, yenileme jetonunuzu ve geliştirici jetonunuzu kitaplığa belirtmeniz gerekir.

Kimlik bilgileriniz zaten varsa...

  • GitHub'daki App.config dosyasından configSections düğümündeki GoogleAdsApi düğümünü ve GoogleAdsApi bölümünü App.config / Web.config dosyanıza kopyalayın. Paketi yüklemek için NuGet'i kullandıysanız bu düğümler otomatik olarak App.config / Web.config dosyanıza eklenir.
  • Geliştirici jetonunu, istemci kimliğini, istemci gizli anahtarını ve yenileme jetonunu uygulamanızın App.config / Web.config bölümüne ekleyin. GitHub'da yer alan App.config dosyası ayrıntılı olarak dokümanlara sahiptir, ancak daha fazla bilgi edinmek ve alternatif yapılandırma ayarlarını kullanmak için Yapılandırma kılavuzuna da bakabilirsiniz.

Kimlik bilgileri oluşturmanız gerekiyorsa...

  • Henüz yoksa geliştirici jetonunuzu almak için Geliştirici jetonu kılavuzundaki adımları uygulayın.
  • İstemci kimliği, istemci gizli anahtarı ve yenileme jetonu oluşturmak için OAuth masaüstü uygulaması akışı kılavuzundaki talimatları uygulayın.
  • GitHub'daki App.config dosyasından configSections düğümündeki GoogleAdsApi düğümünü ve GoogleAdsApi bölümünü App.config / Web.config dosyanıza kopyalayın. Paketi yüklemek için NuGet'i kullandıysanız bu düğümler otomatik olarak App.config / Web.config dosyanıza eklenir.
  • Geliştirici jetonunu, istemci kimliğini, istemci gizli anahtarını ve yenileme jetonunu uygulamanızın App.config / Web.config bölümüne ekleyin. GitHub'da yer alan App.config dosyası ayrıntılı olarak dokümanlara sahiptir, ancak daha fazla bilgi edinmek ve alternatif yapılandırma ayarlarını kullanmak için Yapılandırma kılavuzuna da bakabilirsiniz.

API çağrısı yapma

İstemci kitaplığının temel kullanımı aşağıda gösterilmiştir:

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

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

// Make more calls to service class.

GoogleAdsClient örneği oluşturma

Google Ads API .NET kitaplığındaki en önemli sınıflar, 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 oluşturucu sağlar. Çeşitli 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.V17.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 numaralandırma nesnelerini bağımsız değişken olarak kabul eder. Örneğin, Google Ads API'nin V17 sürümü için CampaignServiceClient örneğini oluşturmak amacıyla yukarıda gösterildiği gibi, bağımsız değişken olarak Services.V17.CampaignService ile GoogleAdsClient.GetService yöntemini çağırmanız gerekir.

İş parçacığı güvenliği

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 etkileyebileceği için GoogleAdsClient örneğini birden fazla iş parçacığı arasında paylaşmak güvenli değildir. GoogleAdsClient örneğinden yeni hizmet örnekleri alma, paralel olarak birden fazla hizmete ç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 donmayı önleme

Eşzamanlı yöntemler, bazı .NET Framework uygulamalarınızın donmasına neden olabilir. Bunun yaygın bir örneği, bir WinForm uygulamasının etkinlik işleyici yönteminden API çağrıları yapmaktır.

Bu sorunu çözmenin iki yolu vardır:

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

    GoogleAdsConfig için UseGrpcCore özelliğini, varsayılan Grpc.Net.Client kitaplığı yerine eski Grpc.Core kitaplığını kullanacak şekilde ayarlayabilirsiniz. Bu yöntem, .NET Framework uygulamalarında kapsamlı olarak test edilmemiştir, bu nedenle sorunu çözemeyebilir. 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öntemleri kullanın.

    Donma durumlarını önlemek için eşzamansız yöntemler kullanabilirsiniz. Bazı örnekler:

    SearchStream

    SearchStream() çağrısı gerçekleştirilir 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.V17.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

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

    private async void button2_Click(object sender, EventArgs e)
{
// Get the BudgetService.
CampaignBudgetServiceClient budgetService = client.GetService(
    Services.V17.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);
}

Eş zamansız yöntemleri iptal etme

Eş zamansız programlama için callSettings parametresini kullanarak bir CancellationToken öğesini iletebilirsiniz:

CancellationTokenSource cancellationTokenSource = new CancellationTokenSource();
cancellationTokenSource.CancelAfter(3000);
CallSettings callSettings = CallSettings.FromCancellationToken(cancellationTokenSource.Token);

string query = "SELECT campaign.name FROM campaign";
var request = new SearchGoogleAdsStreamRequest()
{
    CustomerId = customerId.ToString(),
    Query = query,
};

GoogleAdsServiceClient googleAdsService = client.GetService(
    Services.V17.GoogleAdsService);

googleAdsService.SearchStream(request,
    delegate (SearchGoogleAdsStreamResponse resp)
    {
        foreach (GoogleAdsRow googleAdsRow in resp.Results)
        {
            // Process the row.
        }
    }, callSettings
);

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 gönderebilir. API hatalarının yakalanması ve uygun şekilde ele alınması önemlidir.

Bir API hatası oluştuğunda GoogleAdsException örneği atılır. Hatayı anlamanıza yardımcı olacak ayrıntılar içerir:

// Get the CampaignService.
CampaignServiceClient campaignService = client.GetService(Services.V17.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}");
}