کار با Protobuf Types

از آنجایی که Google Ads API از Protobuf به عنوان فرمت بار پیش‌فرض خود استفاده می‌کند، درک چند قرارداد و انواع 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 وجود دارد.

نسخه 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 هستند.

کتابخانه دات نت، فیلدهای 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 بازنویسی می کند.

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

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