Memulai

Panduan ini memberikan ringkasan singkat tentang cara memulai library .NET Google Ads API.

Penginstalan

Biner library klien didistribusikan menggunakan NuGet. Tambahkan referensi NuGet ke paket Google.Ads.GoogleAds dalam project Anda untuk menggunakan library klien.

Menyiapkan otorisasi

Untuk mengizinkan panggilan API, Anda harus menetapkan client ID, rahasia klien, token refresh, dan token developer ke library.

Jika Anda perlu membuat kredensial

Jika Anda sudah memiliki kredensial

  • Salin node GoogleAdsApi dan bagian GoogleAdsApi di bawah node configSections dari file App.config di GitHub ke dalam file App.config / Web.config Anda. Jika Anda menggunakan NuGet untuk menginstal paket, node ini akan otomatis disisipkan ke dalam file App.config / Web.config Anda.
  • Sertakan token developer, client ID, rahasia klien, dan token refresh di App.config / Web.config aplikasi Anda.

File App.config yang disertakan di GitHub didokumentasikan dengan baik, tetapi Anda juga dapat membaca Panduan konfigurasi untuk mempelajari lebih lanjut serta menggunakan cara alternatif untuk mengonfigurasi library klien, seperti variabel lingkungan.

Melakukan panggilan API

Penggunaan dasar library klien adalah sebagai berikut:

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

Membuat instance GoogleAdsClient

Class yang paling penting dalam library .NET Google Ads API adalah class GoogleAdsClient. Dengan class ini, Anda dapat membuat class layanan yang telah dikonfigurasi sebelumnya yang dapat digunakan untuk melakukan panggilan API. GoogleAdsClient menyediakan konstruktor default yang membuat objek pengguna menggunakan setelan yang ditentukan dalam App.config / Web.config aplikasi Anda. Lihat Panduan konfigurasi untuk mengetahui opsi konfigurasi.

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

Membuat service

GoogleAdsClient menyediakan metode GetService yang dapat digunakan untuk membuat layanan Ads.

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

Kami menyediakan class Services yang menghitung semua versi dan layanan API yang didukung. Metode GetService menerima objek enumerasi ini sebagai argumen saat membuat layanan. Misalnya, untuk membuat instance CampaignServiceClient untuk Google Ads API versi V18, Anda perlu memanggil metode GoogleAdsClient.GetService dengan Services.V18.CampaignService sebagai argumen, seperti yang ditunjukkan dalam contoh sebelumnya.

Keamanan thread

Membagikan instance GoogleAdsClient di antara beberapa thread tidak aman, karena perubahan konfigurasi yang Anda buat pada instance di satu thread dapat memengaruhi layanan yang Anda buat di thread lain. Operasi seperti memperoleh instance layanan baru dari instance GoogleAdsClient dan melakukan panggilan ke beberapa layanan secara paralel aman untuk thread.

Aplikasi multi-thread akan terlihat seperti ini:

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

Menghindari berhenti berfungsi di aplikasi .NET Framework

Metode sinkron dapat menyebabkan beberapa aplikasi .NET Framework Anda terhenti. Contoh umum adalah melakukan panggilan API dari metode pengendali peristiwa aplikasi WinForm.

Ada dua cara untuk mengatasi masalah ini:

  1. Gunakan library Grpc lama.

    Anda dapat menetapkan properti UseGrpcCore dari GoogleAdsConfig untuk menggunakan library Grpc.Core lama, bukan library Grpc.Net.Client default. Metode ini belum diuji secara ekstensif pada aplikasi .NET Framework, sehingga mungkin tidak menyelesaikan masalah. Berikut adalah contoh cuplikan:

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

    Halaman dukungan gRPC memiliki detail lebih lanjut tentang perbedaan antara library Grpc.Core lama dan library Grpc.Net.Client default.

  2. Gunakan metode asinkron.

    Anda dapat menggunakan metode asinkron untuk menghindari pembekuan. Berikut beberapa contohnya:

    SearchStream

    Panggilan ke SearchStream() dilakukan, dan hasilnya diisi ke dalam tampilan daftar.

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

    Anggaran Kampanye

    Panggilan CampaignBudget dibuat, dan nama resource anggaran baru ditampilkan menggunakan pemberitahuan MessageBox.

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

Penanganan error

Tidak semua panggilan API akan berhasil. Server dapat menampilkan error jika panggilan API Anda gagal karena alasan tertentu. Penting untuk menangkap error API dan menanganinya secara tepat.

Instance GoogleAdsException ditampilkan saat terjadi error API. Laporan ini berisi detail untuk membantu Anda mencari tahu masalahnya:

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