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

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

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

تم وضع علامة optional على العديد من الحقول في Google Ads API. يتيح لك هذا التمييز بين الحالات التي يحتوي فيها الحقل على قيمة فارغة، بدلاً من عدم إرسال الخادم قيمة للحقل. تعمل هذه الحقول مثل الحقول العادية، باستثناء أنّها توفّر أيضًا طرقًا إضافية لمحو الحقل والتحقّق ممّا إذا كان الحقل قد تم ضبطه.

على سبيل المثال، يتم وضع علامة على الحقل 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 Ads API، ما يعني أنّ الحقل يمكن أن يتضمّن أنواعًا مختلفة، ولكن بقيمة واحدة فقط في كل مرّة. يشبه أحد الحقول نوع الاتحاد في 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);