العمل مع أنواع 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 }
};

أحد الأنواع

تمّ تمييز بعض الحقول في Google Ads API على أنّها حقول OneOf، ما يعني أنّ الحقل يمكن أن يتضمّن أنواعًا مختلفة ولكن على قيمة واحدة فقط في كل مرّة. يشبه أحد الحقول نوع الاتحاد في C.

تنفذ مكتبة .NET أحد الحقول من خلال توفير خاصية واحدة لكل نوع من القيم التي يمكن الاحتفاظ بها في حقل 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_; }
    }
}

ونظرًا لأن أحد المواقع يتشارك في مساحة التخزين، فيمكن لإحدى المهام أن تحلّ محل مهمة سابقة، ما يؤدي إلى حدوث أخطاء دقيقة. على سبيل المثال:

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