Memulai

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

Penginstalan

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

Menyiapkan otorisasi

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

Jika Anda sudah memiliki kredensial...

  • Salin node GoogleAdsApi dan bagian GoogleAdsApi di bawah node configSections dari file App.config di GitHub ke file App.config / Web.config Anda. Jika Anda menggunakan NuGet untuk menginstal paket, node ini akan otomatis dimasukkan 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 melihat Panduan konfigurasi untuk mempelajari lebih lanjut serta menggunakan setelan konfigurasi alternatif.

Jika Anda perlu membuat kredensial...

  • Ikuti Panduan token developer untuk mendapatkan token developer Anda, jika Anda belum memilikinya.
  • Ikuti panduan alur aplikasi desktop OAuth untuk membuat client ID, rahasia klien, dan token refresh.
  • Salin node GoogleAdsApi dan bagian GoogleAdsApi di bawah node configSections dari file App.config di GitHub ke file App.config/Web.config Anda. Jika Anda menggunakan NuGet untuk menginstal paket, node ini akan otomatis dimasukkan 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 melihat Panduan konfigurasi untuk mempelajari lebih lanjut serta menggunakan setelan konfigurasi alternatif.

Melakukan panggilan API

Penggunaan dasar library klien ditampilkan di bawah ini:

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

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

// Make more calls to service class.

Membuat instance GoogleAdsClient

Class terpenting di library .NET Google Ads API adalah class GoogleAdsClient. Dengan class ini, Anda dapat membuat class layanan yang telah dikonfigurasi sebelumnya dan 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 berbagai opsi konfigurasi.

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

Membuat layanan

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

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

Kami menyediakan class Services yang memerinci 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 V11, Anda perlu memanggil metode GoogleAdsClient.GetService dengan Services.V11.CampaignService sebagai argumen, seperti yang ditunjukkan di atas.

Keamanan thread

Instance GoogleAdsClient tidak dapat dibagikan di antara beberapa thread, karena perubahan konfigurasi yang Anda buat pada instance di satu thread dapat memengaruhi layanan yang Anda buat di thread lain. Operasi seperti mendapatkan instance layanan baru dari instance GoogleAdsClient, membuat panggilan ke beberapa layanan secara paralel, dll., aman untuk thread.

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

Membatalkan metode asinkron

Untuk pemrograman asinkron, Anda dapat menggunakan parameter callSettings untuk meneruskan CancellationToken:

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.V11.GoogleAdsService);

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

Penanganan error

Tidak semua panggilan API akan berhasil. Server dapat menampilkan error jika panggilan API Anda gagal karena beberapa alasan. Penting untuk menangkap error API dan menanganinya dengan benar.

Instance GoogleAdsException ditampilkan jika terjadi error API. Panduan ini berisi detail untuk membantu Anda mencari tahu apa yang salah:

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