کار با Protobuf Types

از آنجایی که Google Ads API از proto3 به عنوان فرمت بار پیش‌فرض خود استفاده می‌کند، درک چند قرارداد و انواع protobuf هنگام کار با API مهم است.

فیلدهای اختیاری

بسیاری از فیلدها در Google Ads API به عنوان optional علامت گذاری شده اند. این به شما امکان می‌دهد بین مواردی که فیلد دارای مقدار خالی است، در مقابل اینکه سرور مقداری را برای فیلد ارسال نکرده است، تمایز قائل شوید. این فیلدها مانند فیلدهای معمولی رفتار می‌کنند، با این تفاوت که روش‌های اضافی را برای پاک کردن فیلد و بررسی تنظیم بودن فیلد نیز ارائه می‌دهند.

به عنوان مثال، فیلد Name شیء Campaign به عنوان اختیاری علامت گذاری شده است. بنابراین برای کار با این زمینه می توانید از روش های زیر استفاده کنید.

// 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 یک کمپین یک فیلد تکراری است، بنابراین به عنوان یک RepeatedField<CustomParameter> فقط خواندنی در کتابخانه مشتری دات نت نشان داده می شود. RepeatedField رابط IList<T> را پیاده سازی می کند.

دو راه برای پر کردن یک فیلد RepeatedField وجود دارد.

روش 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" }
 });
 ```

دستور اولیه مجموعه

// 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 است.

کتابخانه دات نت 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.ManualCpc اکنون از آنجایی که مقداردهی اولیه شده است campaign.ManualCpm null است. فیلد ManualCpm مقدار اولیه اولیه را برای campaign.ManualCpc بازنویسی می کند.

تبدیل به فرمت های دیگر

تبدیل به فرمت JSON

می توانید اشیاء 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);