العمل مع أنواع 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> من واجهة pyplot.

تتوفّر طريقتان لتعبئة حقل 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. . ويتم تنفيذ هذه الفئة على النحو التالي (تم تبسيط الرمز للإيجاز):

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