Temel kullanım

.NET istemci kitaplığının temel kullanımı aşağıdaki gibidir:

// Initialize a GoogleAdsConfig instance.
GoogleAdsConfig config = new GoogleAdsConfig()
{
    OAuth2Mode = OAuth2Flow.SERVICE_ACCOUNT,
    OAuth2SecretsJsonPath = "PATH_TO_CREDENTIALS_JSON",
    LoginCustomerId = "INSERT_LOGIN_CUSTOMER_ID_HERE"
};

// Initialize a GoogleAdsClient instance.
GoogleAdsClient client = new GoogleAdsClient(config);

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

// Make calls to the service client.

İstemciyi ve hizmetleri başlatma

Google Ads API ile etkileşim kurmak için önce bir GoogleAdsClient yapılandırıp örneğini oluşturun, ardından ihtiyacınız olan belirli API hizmeti istemcilerini oluşturmak için bu GoogleAdsClient'yı kullanın.

GoogleAdsClient örneği oluşturma

Google Ads API .NET kitaplığındaki en önemli sınıf GoogleAdsClient sınıfıdır. Bu kitaplık, API çağrıları yapmak için kullanılabilecek önceden yapılandırılmış bir hizmet istemcisi oluşturmanıza olanak tanır. GoogleAdsClient nesnesini yapılandırmak için GoogleAdsConfig nesnesi oluşturun ve gerekli özellikleri ayarlayın. Daha fazla bilgi için yapılandırma kılavuzuna bakın.

// Initialize a GoogleAdsConfig instance.
GoogleAdsConfig config = new GoogleAdsConfig()
{
    OAuth2Mode = OAuth2Flow.SERVICE_ACCOUNT,
    OAuth2SecretsJsonPath = "PATH_TO_CREDENTIALS_JSON",
    LoginCustomerId = "INSERT_LOGIN_CUSTOMER_ID_HERE"
};

// Initialize a GoogleAdsClient instance.
GoogleAdsClient client = new GoogleAdsClient(config);

// Modify the GoogleAdsClient configuration afterwards if needed.
client.Config.LoginCustomerId = "INSERT_UPDATED_LOGIN_CUSTOMER_ID_HERE";

Hizmet oluştur

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

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

Kitaplık, desteklenen tüm API sürümlerini (v25.1 gibi küçük sürümler, ana sürüm numaralandırmasını kullanır, Services.V25) ve hizmetlerini numaralandıran bir Services sınıfı sağlar. GetService yöntemi, hizmet oluşturulurken bu numaralandırma nesnelerini bağımsız değişken olarak kabul eder. Örneğin, Google Ads API'nin V25 sürümü için CampaignServiceClient örneği oluşturmak üzere önceki örnekte gösterildiği gibi GoogleAdsClient.GetService yöntemini bağımsız değişken olarak Services.V25.CampaignService ile çağırın.

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 hatalar döndürebilir. API hatalarını yakalamak ve uygun şekilde ele almak önemlidir.

API hatası oluştuğunda GoogleAdsException örneği oluşturulur. Bu mesajda, neyin yanlış gittiğini anlamanıza yardımcı olacak ayrıntılar yer alır:

public void Run(GoogleAdsClient client, long customerId)
{
    // Get the GoogleAdsService.
    GoogleAdsServiceClient googleAdsService = client.GetService(
        Services.V25.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";

    try
    {
        // Issue a search request.
        googleAdsService.SearchStream(customerId.ToString(), query,
            delegate (SearchGoogleAdsStreamResponse resp)
            {
                foreach (GoogleAdsRow googleAdsRow in resp.Results)
                {
                    Console.WriteLine("Campaign with ID {0} and name '{1}' was found.",
                        googleAdsRow.Campaign.Id, googleAdsRow.Campaign.Name);
                }
            }
        );
    }
    catch (GoogleAdsException e)
    {
        Console.WriteLine("Failure:");
        Console.WriteLine($"Message: {e.Message}");
        Console.WriteLine($"Failure: {e.Failure}");
        Console.WriteLine($"Request ID: {e.RequestId}");
        throw;
    }
}

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

Paylaşılan bir GoogleAdsClient örneğinin yapılandırma durumunu birden fazla iş parçacığında değiştirmek iş parçacığı açısından güvenli değildir. Bunun nedeni, bir iş parçacığındaki bir örnekte yaptığınız yapılandırma değişikliklerinin diğer iş parçacıklarında oluşturduğunuz hizmetleri etkileyebilmesidir. Ancak, değişmeyen bir GoogleAdsClient örneğinden yeni hizmet örnekleri alma ve birden fazla hizmete paralel olarak çağrı yapma gibi salt okunur işlemler iş parçacığı açısından güvenlidir.

İş parçacığı başına yapılandırma değişikliklerini yalıtmak için her çalışan görevi veya iş parçacığı için ayrı bir GoogleAdsClient oluşturun:

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

Task task1 = Task.Run(() => AddAdGroups(client1));
Task task2 = Task.Run(() => AddAdGroups(client2));

await Task.WhenAll(task1, task2);

public void AddAdGroups(GoogleAdsClient client)
{
    // Perform operations with client.
}

Uygulamanızın yanıt vermesini sağlama

Google Ads API yöntem çağrılarının tamamlanması, isteklerin boyutuna bağlı olarak biraz zaman alabilir. Uygulamanızın yanıt vermeye devam etmesini sağlamak için aşağıdaki adımları uygulayın:

Eski kullanıcı arayüzü çerçeveleri için Grpc.Core kitaplığını kullanma

.NET Framework'ü hedefleyen ve ASP.NET Web Forms veya WinForms gibi eski bir kullanıcı arayüzü teknolojisi kullanan bir uygulama geliştiriyorsanız eski Grpc.Core aktarım kitaplığını aşağıdaki şekilde etkinleştirebilirsiniz:

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

Eşzamansız yöntemleri kullanma

Uygulamanızın yanıt vermeye devam etmesini sağlamak için eşzamansız yöntemler kullanabilirsiniz. Aşağıda birkaç örnek verilmiştir.

Kampanya listesini alın ve ListView doldurun.

private async void OnRetrieveCampaignsButtonClick(object sender, EventArgs e)
{
    try
    {
        // Get the GoogleAdsService.
        GoogleAdsServiceClient googleAdsService = client.GetService(
            Services.V25.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<ListViewItem> items = new List<ListViewItem>();
        await googleAdsService.SearchStreamAsync(
            customerId.ToString(),
            query,
            (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);
                }
            }
        );
        listView1.Items.AddRange(items.ToArray());
    }
    catch (GoogleAdsException ex)
    {
        MessageBox.Show($"API Error: {ex.Message}");
    }
}

Kampanya bütçesini güncelleme ve mesaj kutusu uyarısı gösterme

private async void OnUpdateBudgetButtonClick(object sender, EventArgs e)
{
    try
    {
        // Get the CampaignBudgetService.
        CampaignBudgetServiceClient budgetService = client.GetService(
            Services.V25.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 asynchronously.
        MutateCampaignBudgetsResponse response =
            await budgetService.MutateCampaignBudgetsAsync(
                customerId.ToString(),
                new CampaignBudgetOperation[] { budgetOperation });

        MessageBox.Show(response.Results[0].ResourceName);
    }
    catch (GoogleAdsException ex)
    {
        MessageBox.Show($"API Error: {ex.Message}");
    }
}