Podstawowe użycie

Podstawowe użycie biblioteki klienta .NET wygląda tak:

// 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.V26.CampaignService);

// Make calls to the service client.

Inicjowanie klienta i usług

Aby korzystać z interfejsu Google Ads API, najpierw skonfiguruj i utwórz instancję GoogleAdsClient, a następnie użyj jej do utworzenia klientów konkretnych usług API, których potrzebujesz.

Tworzenie instancji GoogleAdsClient

Najważniejszą klasą w bibliotece .NET interfejsu Google Ads API jest klasa GoogleAdsClient. Umożliwia ona tworzenie wstępnie skonfigurowanego klienta usługi, którego można używać do wykonywania wywołań interfejsu API. Aby skonfigurować obiekt GoogleAdsClient, utwórz obiekt GoogleAdsConfig i ustaw wymagane właściwości. Więcej informacji znajdziesz w przewodniku po konfiguracji.

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

Tworzenie usługi

GoogleAdsClient udostępnia metodę GetService, której można użyć do utworzenia klienta usługi API.

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

Biblioteka udostępnia klasę Services, która zawiera listę wszystkich obsługiwanych wersji interfejsu API (w przypadku wersji pomocniczych, takich jak v25.1, używana jest wyliczenie wersji głównej, Services.V25) i usług. Podczas tworzenia usługi metoda GetService przyjmuje te obiekty wyliczeniowe jako argument. Aby na przykład utworzyć instancję CampaignServiceClient dla wersji V26 interfejsu Google Ads API, wywołaj metodę GoogleAdsClient.GetService z argumentem Services.V26.CampaignService, jak pokazano w poprzednim przykładzie.

Obsługa błędów

Nie każde wywołanie interfejsu API kończy się powodzeniem. Jeśli wywołania interfejsu API nie powiodą się z jakiegoś powodu, serwer może zwrócić błędy. Ważne jest, aby przechwytywać błędy interfejsu API i odpowiednio je obsługiwać.

Gdy wystąpi błąd interfejsu API, zgłaszana jest instancja GoogleAdsException. Zawiera ona szczegółowe informacje, które pomogą Ci ustalić, co poszło nie tak:

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

Bezpieczeństwo wątków

Modyfikowanie stanu konfiguracji współdzielonej instancji GoogleAdsClient w wielu wątkach nie jest wątkowo bezpieczne, ponieważ zmiany konfiguracji wprowadzone w instancji w jednym wątku mogą wpływać na usługi tworzone w innych wątkach. Operacje tylko do odczytu, takie jak uzyskiwanie nowych instancji usługi z niezmiennej instancji GoogleAdsClient i równoległe wywoływanie wielu usług, są jednak wątkowo bezpieczne.

Aby odizolować zmiany konfiguracji w poszczególnych wątkach, utwórz oddzielną instancję GoogleAdsClient dla każdego zadania lub wątku roboczego:

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.
}

Zapewnianie responsywności aplikacji

Wywołania metod interfejsu Google Ads API mogą potrwać dłużej, w zależności od rozmiaru żądań. Aby zapewnić responsywność aplikacji:

Używanie biblioteki Grpc.Core w starszych platformach interfejsu

Jeśli tworzysz aplikację, która jest przeznaczona dla platformy .NET Framework i korzysta ze starszej technologii interfejsu, takiej jak ASP.NET Web Forms lub WinForms, możesz włączyć starszą bibliotekę transportu Grpc.Core w ten sposób:

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

Używanie metod asynchronicznych

Aby zapewnić responsywność aplikacji, możesz używać metod asynchronicznych. Oto kilka przykładów.

Pobieranie listy kampanii i wypełnianie elementu ListView

private async void OnRetrieveCampaignsButtonClick(object sender, EventArgs e)
{
    try
    {
        // Get the GoogleAdsService.
        GoogleAdsServiceClient googleAdsService = client.GetService(
            Services.V26.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}");
    }
}

Aktualizowanie budżetu kampanii i wyświetlanie okna komunikatu

private async void OnUpdateBudgetButtonClick(object sender, EventArgs e)
{
    try
    {
        // Get the CampaignBudgetService.
        CampaignBudgetServiceClient budgetService = client.GetService(
            Services.V26.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}");
    }
}