시작하기

경고: 버전 19.0.0부터 .NET용 Google Ads API 클라이언트 라이브러리는 더 이상 .NET 5.0을 지원하지 않습니다. 원활한 작동을 위해 2024년 말 이전에 .NET 버전을 업그레이드하는 것이 좋습니다.

이 가이드에서는 Google Ads API .NET 라이브러리를 시작하는 방법을 간략히 설명합니다.

설치

클라이언트 라이브러리 바이너리는 NuGet을 사용하여 배포됩니다. 클라이언트 라이브러리를 사용하려면 프로젝트의 Google.Ads.GoogleAds 패키지에 NuGet 참조를 추가합니다.

승인 설정하기

API 호출을 승인하려면 클라이언트 ID, 클라이언트 보안 비밀번호, 갱신 토큰, 개발자 토큰을 라이브러리에 지정해야 합니다.

사용자 인증 정보를 생성해야 하는 경우

• 아직 개발자 토큰이 없는 경우 개발자 토큰 가이드에 따라 개발자 토큰을 가져옵니다.
• OAuth 데스크톱 앱 흐름 가이드를 따라 클라이언트 ID, 클라이언트 보안 비밀번호, 새로고침 토큰을 생성합니다.

이미 사용자 인증 정보가 있는 경우

• GitHub의 App.config 파일에서 GoogleAdsApi 노드와 configSections 노드 아래의 GoogleAdsApi 섹션을 App.config / Web.config 파일에 복사합니다. NuGet을 사용하여 패키지를 설치한 경우 이러한 노드가 App.config / Web.config 파일에 자동으로 삽입됩니다.
• 앱의 App.config / Web.config에 개발자 토큰, 클라이언트 ID, 클라이언트 비밀번호, 갱신 토큰을 포함합니다.

GitHub에 포함된 App.config 파일은 문서가 잘 작성되어 있지만 구성 가이드를 참고하여 자세히 알아보고 환경 변수와 같은 다른 방법으로 클라이언트 라이브러리를 구성할 수도 있습니다.

API 호출

클라이언트 라이브러리의 기본 사용법은 다음과 같습니다.

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

GoogleAdsClient 인스턴스 만들기

Google Ads API .NET 라이브러리에서 가장 중요한 클래스는 GoogleAdsClient 클래스입니다. 이를 통해 API 호출에 사용할 수 있는 사전 구성된 서비스 클래스를 만들 수 있습니다. GoogleAdsClient는 앱의 App.config / Web.config에 지정된 설정을 사용하여 사용자 객체를 만드는 기본 생성자를 제공합니다. 구성 옵션은 구성 가이드를 참고하세요.

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

서비스 만들기

GoogleAdsClient는 광고 서비스를 만드는 데 사용할 수 있는 GetService 메서드를 제공합니다.

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

지원되는 모든 API 버전과 서비스를 열거하는 Services 클래스를 제공합니다. GetService 메서드는 서비스를 만들 때 이러한 열거형 객체를 인수로 받습니다. 예를 들어 Google Ads API 버전 V18의 CampaignServiceClient 인스턴스를 만들려면 이전 예와 같이 Services.V18.CampaignService를 인수로 사용하여 GoogleAdsClient.GetService 메서드를 호출해야 합니다.

스레드 안전

한 스레드의 인스턴스에서 구성을 변경하면 다른 스레드에서 만드는 서비스에 영향을 줄 수 있으므로 여러 스레드 간에 GoogleAdsClient 인스턴스를 공유하는 것은 안전하지 않습니다. GoogleAdsClient 인스턴스에서 새 서비스 인스턴스를 가져오고 여러 서비스를 동시에 호출하는 등의 작업은 스레드로부터 안전합니다.

멀티스레드 애플리케이션은 다음과 같이 표시됩니다.

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

.NET Framework 애플리케이션에서 정지 방지

동기식 메서드로 인해 일부 .NET Framework 애플리케이션이 정지될 수 있습니다. 일반적인 예는 WinForm 애플리케이션의 이벤트 핸들러 메서드에서 API를 호출하는 것입니다.

이 문제를 해결하는 방법에는 두 가지가 있습니다.

1. 기존 Grpc 라이브러리를 사용합니다.

   기본 Grpc.Net.Client 라이브러리 대신 기존 Grpc.Core 라이브러리를 사용하도록 GoogleAdsConfig의 UseGrpcCore 속성을 설정할 수 있습니다. 이 방법은 .NET Framework 애플리케이션에서 광범위하게 테스트되지 않았으므로 문제가 해결되지 않을 수 있습니다. 다음은 샘플 스니펫입니다.

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

2. 비동기 메서드를 사용합니다.

   비동기 메서드를 사용하여 정지를 방지할 수 있습니다. 예를 들면 다음과 같습니다.

   SearchStream

   SearchStream() 호출이 실행되고 결과가 목록 뷰에 채워집니다.

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

   캠페인 예산

   CampaignBudget 호출이 생성되고 새 예산의 리소스 이름이 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);
   }
   

오류 처리

모든 API 호출이 성공하는 것은 아닙니다. 어떤 이유로든 API 호출이 실패하면 서버에서 오류가 발생할 수 있습니다. API 오류를 포착하고 적절하게 처리하는 것이 중요합니다.

API 오류가 발생하면 GoogleAdsException 인스턴스가 발생합니다. 문제의 원인을 파악하는 데 도움이 되는 세부정보가 포함되어 있습니다.

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