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.V25.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 potrzebnych klientów usług interfejsu API.

Tworzenie instancji GoogleAdsClient

Najważniejszą klasą w bibliotece .NET interfejsu Google Ads API jest klasa GoogleAdsClient. Umożliwia utworzenie 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";

Utwórz usługę

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

CampaignServiceClient campaignService = client.GetService(
    Services.V25.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. Metoda GetService akceptuje te obiekty wyliczeniowe jako argument podczas tworzenia usługi. Aby na przykład utworzyć instancję CampaignServiceClient w wersji V25 interfejsu Google Ads API, wywołaj metodę GoogleAdsClient.GetService z argumentem Services.V25.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 z jakiegoś powodu się nie powiodą, serwer może zwrócić błędy. Ważne jest, aby rejestrować błędy interfejsu API i odpowiednio je obsługiwać.

Gdy wystąpi błąd interfejsu API, zgłaszana jest instancja GoogleAdsException. Zawiera on szczegóły, 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.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;
    }
}

Bezpieczeństwo wątków

Modyfikowanie stanu konfiguracji udostępnionej instancji GoogleAdsClient w wielu wątkach nie jest bezpieczne dla wątków, ponieważ zmiany konfiguracji wprowadzone w instancji w jednym wątku mogą mieć wpływ na usługi tworzone w innych wątkach. Operacje tylko do odczytu, takie jak uzyskiwanie nowych instancji usługi z niezmiennej instancji GoogleAdsClient i wykonywanie wywołań do wielu usług równolegle, są jednak bezpieczne dla wątków.

Aby odizolować zmiany konfiguracji poszczególnych wątków, utwórz osobny obiekt GoogleAdsClient dla każdego zadania lub wątku pracownika:

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

Zadbaj o szybkie działanie aplikacji

Wywołania metod interfejsu Google Ads API mogą potrwać dłużej w zależności od wielkości żądań. Aby aplikacja działała sprawnie, wykonaj te czynności:

Korzystanie z biblioteki Grpc.Core w przypadku starszych platform interfejsu

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

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

Używanie metod asynchronicznych

Aby aplikacja działała sprawnie, możesz używać metod asynchronicznych. Oto kilka przykładów.

Pobierz listę kampanii i wypełnij ListView.

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}");
    }
}

Aktualizowanie budżetu kampanii i wyświetlanie alertu w oknie komunikatu

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}");
    }
}