protobuf 유형 작업

Google Ads API는 proto3를 기본 페이로드 형식으로 사용하므로 .NET 클라이언트 라이브러리로 작업할 때는 몇 가지 프로토콜 버퍼 규칙과 유형을 이해하는 것이 중요합니다.

선택적 필드

Google Ads API의 많은 필드가 optional로 표시됩니다. 이렇게 하면 필드에 빈 값이 있는 경우와 서버에서 필드 값을 반환하지 않는 경우를 구분할 수 있습니다. 이러한 필드는 일반 속성처럼 작동하지만 필드를 지우고 필드가 설정되었는지 확인하는 추가 메서드도 제공합니다.

예를 들어 Campaign 객체의 Name 필드는 optional로 표시되므로 다음 메서드를 사용하여 이 필드를 사용할 수 있습니다.

// Get the name.
string name = campaign.Name;

// Set the name.
campaign.Name = name;

// Check if the campaign object has the name field set.
bool hasName = campaign.HasName();

// Clear the name field. Use this method to exclude the Name field from
// being sent to the server in a subsequent API call.
campaign.ClearName();

// Set the campaign name to an empty string value. This value will be
// sent to the server if you use this object in a subsequent API call.
campaign.Name = "";

// This throws a runtime ArgumentNullException. Use ClearName() instead.
campaign.Name = null;

반복 필드

필드 배열은 Google Ads API에서 읽기 전용 RepeatedField로 표시됩니다.

예를 들어 캠페인의 url_custom_parameters 필드는 반복 필드이므로 .NET 클라이언트 라이브러리에서 읽기 전용 RepeatedField<CustomParameter>로 표시됩니다. RepeatedField<T>는 IList<T> 인터페이스를 구현합니다.

RepeatedField 속성을 채우는 방법에는 두 가지가 있습니다.

AddRange 메서드

Campaign campaign = new Campaign()
{
    ResourceName = ResourceNames.Campaign(customerId, campaignId),
    Status = CampaignStatus.Paused,
};

// Add values to UrlCustomParameters using the AddRange method.
campaign.UrlCustomParameters.AddRange(new CustomParameter[]
{
    new CustomParameter { Key = "season", Value = "christmas" },
    new CustomParameter { Key = "promocode", Value = "NY123" }
});

컬렉션 이니셜라이저 문법

// Option 1: Initialize the field directly.
Campaign campaign = new Campaign()
{
    ResourceName = ResourceNames.Campaign(customerId, campaignId),
    Status = CampaignStatus.Paused,
    // Directly initialize the field.
    UrlCustomParameters =
    {
        new CustomParameter { Key = "season", Value = "christmas" },
        new CustomParameter { Key = "promocode", Value = "NY123" }
    }
};

// Option 2: Initialize using an intermediate variable.
CustomParameter[] parameters = new CustomParameter[]
{
    new CustomParameter { Key = "season", Value = "christmas" },
    new CustomParameter { Key = "promocode", Value = "NY123" }
};

Campaign campaign1 = new Campaign()
{
    ResourceName = ResourceNames.Campaign(customerId, campaignId),
    Status = CampaignStatus.Paused,
    // Initialize from an existing array.
    UrlCustomParameters = { parameters }
};

Oneof 필드

Google Ads API의 일부 필드는 oneof 필드로 표시됩니다. 즉, 필드에 여러 유형이 포함될 수 있지만 한 번에 하나의 값만 포함될 수 있습니다. oneof 필드는 C 프로그래밍 언어의 공용체 유형과 유사합니다.

.NET 라이브러리는 oneof 필드에 저장할 수 있는 각 값 유형에 하나의 속성을 제공하여 oneof 필드를 구현하며, 모든 속성은 공유 기본 저장소 필드를 업데이트합니다.

예를 들어 캠페인의 campaign_bidding_strategy은 oneof 필드로 표시됩니다. 이 클래스는 다음과 같이 구현됩니다 (간결성을 위해 코드가 단순화됨).

public sealed partial class Campaign : pb::IMessage<Campaign>
{
    object campaignBiddingStrategy_ = null;
    CampaignBiddingStrategyOneofCase campaignBiddingStrategyCase_;

    public ManualCpc ManualCpc
    {
        get
        {
            return campaignBiddingStrategyCase_ ==
                CampaignBiddingStrategyOneofCase.ManualCpc
                ? (ManualCpc)campaignBiddingStrategy_ : null;
        }
        set
        {
            campaignBiddingStrategy_ = value;
            campaignBiddingStrategyCase_ =
                CampaignBiddingStrategyOneofCase.ManualCpc;
        }
    }

    public ManualCpm ManualCpm
    {
        get
        {
            return campaignBiddingStrategyCase_ ==
                CampaignBiddingStrategyOneofCase.ManualCpm
                ? (ManualCpm)campaignBiddingStrategy_ : null;
        }
        set
        {
            campaignBiddingStrategy_ = value;
            campaignBiddingStrategyCase_ =
                CampaignBiddingStrategyOneofCase.ManualCpm;
        }
    }

    public CampaignBiddingStrategyOneofCase CampaignBiddingStrategyCase
    {
        get { return campaignBiddingStrategyCase_; }
    }
}

oneof 속성은 저장소를 공유하므로 하나의 할당이 이전 할당을 덮어쓸 수 있어 미묘한 버그가 발생할 수 있습니다. 예를 들면 다음과 같습니다.

Campaign campaign = new Campaign()
{
    ManualCpc = new ManualCpc(),
    ManualCpm = new ManualCpm()
};

이 경우 campaign.ManualCpc은 null입니다. campaign.ManualCpm 속성을 초기화하면 campaign.ManualCpc의 이전 초기화가 덮어쓰여지기 때문입니다.

다른 형식으로 변환

JSON 형식으로 변환

Google.Protobuf.JsonFormatter를 사용하여 protobuf 객체를 JSON 형식으로 변환하고 다시 변환할 수 있습니다. 이는 JSON이나 XML과 같은 텍스트 기반 형식이 필요한 다른 시스템과 인터페이스해야 하는 시스템을 빌드할 때 유용합니다.

using Google.Protobuf;

GoogleAdsRow row = new GoogleAdsRow()
{
    Campaign = new Campaign()
    {
        Id = 123,
        Name = "Campaign 1",
        ResourceName = ResourceNames.Campaign(1234567890, 123)
    }
};

// Serialize to JSON and back.
string json = JsonFormatter.Default.Format(row);
row = GoogleAdsRow.Parser.ParseJson(json);

바이트로 변환

Google.Protobuf를 사용하여 객체를 바이트로 직렬화하고 다시 직렬화할 수 있습니다. 바이너리 직렬화는 JSON 형식보다 메모리 및 스토리지 효율성이 높습니다.

using Google.Protobuf;

GoogleAdsRow row = new GoogleAdsRow()
{
    Campaign = new Campaign()
    {
        Id = 123,
        Name = "Campaign 1",
        ResourceName = ResourceNames.Campaign(1234567890, 123)
    }
};

// Serialize to bytes and back.
byte[] bytes = row.ToByteArray();
row = GoogleAdsRow.Parser.ParseFrom(bytes);