Protobuf 유형 작업

Google Ads API는 Protobuf를 기본 페이로드 형식으로 사용하므로 API 작업 시 몇 가지 Protobuf 규칙과 유형을 이해하는 것이 중요합니다.

선택적 필드

Google Ads API의 많은 필드가 optional로 표시됩니다. 이를 통해 필드의 값이 비어 있는 경우와 서버가 필드의 값을 다시 전송하지 않은 경우를 구분할 수 있습니다. 이러한 필드는 필드를 지우고 필드가 설정되었는지 확인하는 추가 메서드를 제공한다는 점을 제외하면 일반 필드처럼 작동합니다.

예를 들어 Campaign 객체의 Name 필드는 선택사항으로 표시되어 있습니다. 따라서 다음 메서드를 사용하여 이 필드를 작업할 수 있습니다.

// 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 Name field from
// being sent to the server in a subsequent API call.
campaign.ClearName();

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

// This will throw a runtime error. Use ClearName() instead.
campaign.Name = null;

반복되는 유형

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

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

RepeatedField는 IList<T> 인터페이스를 구현합니다.

RepeatedField 필드를 채우는 방법에는 두 가지가 있습니다.

이전 C# 버전: AddRange 메서드를 사용하여 값 추가

아래 예시를 참고하세요.

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

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

최신 C# 버전: 컬렉션 이니셜라이저 구문 사용

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

유형 중 하나

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()
    {
        EnhancedCpcEnabled = true
    },
    ManualCpm = new ManualCpm()
    {

    }
};

이 경우 campaign.ManualCpm 필드를 초기화하면 campaign.ManualCpc의 이전 초기화를 덮어쓰므로 campaign.ManualCpc는 이제 null입니다.

다른 형식으로 변환

protobuf 객체를 JSON 형식으로 쉽게 변환하고 그 반대로 변환할 수 있습니다. 이는 JSON 또는 XML과 같은 텍스트 기반 형식의 데이터가 필요한 다른 시스템과 인터페이스해야 하는 시스템을 빌드할 때 유용합니다.

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

객체를 바이트로 직렬화하거나 다시 직렬화할 수도 있습니다. 바이너리 직렬화는 JSON 형식보다 메모리와 저장용량 효율성이 높습니다.

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