العمل مع أنواع Protobuf

نظرًا لأن Google Ads API تستخدم Protobuf كتنسيق افتراضي للحمولة، فمن المهم فهم بعض اصطلاحات وأنواع Protobuf عند التعامل مع API.

حقول اختيارية

العديد من الحقول في إعلانات Google 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> للقراءة فقط في مكتبة عميل NET..

يستخدم 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 }
};

أنواع OneOf

يتم وضع علامة على بعض الحقول في إعلانات Google 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.ManualCpc الآن null بما أنّ تهيئة الحقل campaign.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);