تحسين الأداء

يتناول هذا المستند بعض الأساليب التي يمكنك استخدامها لتحسين أداء تطبيقك. في بعض الحالات، يتم استخدام أمثلة من واجهات برمجة تطبيقات أخرى تم تنفيذها لتوضيح الأفكار المقدمة. ومع ذلك، تنطبق نفس المفاهيم على الشاشة Video 360 API:

استخدام الموارد الجزئية

هناك طريقة أخرى لتحسين أداء طلبات البيانات من واجهة برمجة التطبيقات وهي من خلال طلب جزء البيانات الذي تهتم به. يتيح هذا الإجراء لتطبيقك وتجنب نقل الحقول غير الضرورية وتحليلها وتخزينها، حتى يتمكن من استخدام الموارد مثل الشبكة ووحدة المعالجة المركزية (CPU) والذاكرة بكفاءة أكبر.

ردّ جزئي

يرسل الخادم تلقائيًا التمثيل الكامل للمورد بعد معالجة الطلبات. للحصول على أداء أفضل، يمكنك أن تطلب من الخادم إرسال فقط الحقول التي تحتاجها حقًا واحصل على رد جزئي بدلاً من ذلك.

لطلب استجابة جزئية، يمكنك استخدام معلَمة طلب fields لتحديد الحقول التي تريد إرجاعها. يمكنك استخدام هذه المعلمة مع أي طلب تقوم بإرجاع بيانات الاستجابة.

مثال

يوضّح المثال التالي استخدام مَعلمة fields مع السمة العرض Video 360 API:

طلب بسيط: يحذف طلب HTTP GET هذا المَعلمة fields بإرجاع المورد بالكامل.

GET https://displayvideo.googleapis.com/v3/advertisers?partnerId=1

الاستجابة الكاملة للموارد: تشمل بيانات الموارد الكاملة ما يلي: إلى جانب العديد من الحقول الأخرى التي تم حذفها للإيجاز.

200 OK

{
 "advertisers": [
  {
   "name": "advertisers/1",
   "advertiserId": "1",
   "partnerId": "1",
   "displayName": "Example Advertiser 1",
   "entityStatus": "ENTITY_STATUS_ACTIVE",
   "updateTime": "2019-01-01T00:00:00.000000Z",
   "generalConfig": {
    "domainUrl": "http://example.com",
    "timeZone": "America/New_York",
    "currencyCode": "USD",
    "address": {
    }
   },
   "adServerConfig": {
    "thirdPartyOnlyConfig": {
    }
   },
   "creativeConfig": {
   },
   "dataAccessConfig": {
    "sdfConfig": {
     "sdfConfig": {
      "version": "VERSION_3_1"
     }
    }
   },
   "integrationDetails": {
   }
  },
  {
   "name": "advertisers/2",
   "advertiserId": "2",
   "partnerId": "1",
   "displayName": "Example Advertiser 2",
   "entityStatus": "ENTITY_STATUS_ACTIVE",
   "updateTime": "2019-01-01T00:00:00.000000Z",
   "generalConfig": {
    "domainUrl": "http://example.com",
    "timeZone": "America/New_York",
    "currencyCode": "USD",
    "address": {
    }
   },
   "adServerConfig": {
    "thirdPartyOnlyConfig": {
    }
   },
   "creativeConfig": {
   },
   "dataAccessConfig": {
    "sdfConfig": {
     "sdfConfig": {
      "version": "VERSION_3_1"
     }
    }
   },
   "integrationDetails": {
   }
  },
  ...
 ],
 "nextPageToken": "..."
}

طلب استجابة جزئية: الطلب التالي لهذا المورد نفسه تستخدم المعلمة fields لتقليل كمية البيانات المعروضة بشكل كبير.

GET https://displayvideo.googleapis.com/v3/advertisers?partnerId=1&fields=advertisers(advertiserId,partnerId,displayName)

الاستجابة الجزئية: استجابةً للطلب أعلاه، يرسل الخادم مرة أخرى يحتوي على مصفوفة معلنة مصغرة تتضمن فقط الرقم التعريفي للمعلِن، والاسم المعروض، وموقع الرقم التعريفي للشريك لكل معلن، إذا حاليًا.

200 OK

{
 "advertisers": [
  {
   "advertiserId": "1",
   "partnerId": "1",
   "displayName": "Example Advertiser 1"
  },
  {
   "advertiserId": "2",
   "partnerId": "1",
   "displayName": "Example Advertiser 2"
  },
  ...
 ]
}

يُرجى العِلم أنّ الردّ هو كائن JSON يتضمّن الحقول المحدّدة فقط. والأشياء الرئيسية المرفقة بها.

وسنتناول بعد ذلك تفاصيل حول كيفية تنسيق مَعلمة fields، تليها مزيد من التفاصيل حول ما يتم عرضه بالضبط في الرد.

ملخّص بنية مَعلمات الحقول

يستند تنسيق قيمة معلَمة طلب fields إلى XPath بشكل غير دقيق وبناء الجملة. يتم تلخيص بناء الجملة المعتمد أدناه، وأمثلة إضافية الواردة في القسم التالي.

• استخدِم قائمة مفصولة بفواصل لاختيار حقول متعددة.

• استخدِم a/b لاختيار الحقل b المتداخل في الحقل a. استخدام a/b/c لاختيار حقل c متداخل في b.

• يمكنك استخدام محدد فرعي لطلب مجموعة من الحقول الفرعية المحددة للصفائف أو عن طريق وضع التعبيرات بين قوسين "( )".

  مثلاً: fields=advertisers(advertiserId,generalConfig/domainUrl) لا تعرض سوى الرقم التعريفي للمعلِن وعنوان URL للنطاق لكل عنصر من عناصر مصفوفة المعلنين. يمكنك أيضًا تحديد حقل فرعي واحد، حيث fields=advertisers(advertiserId) تساوي fields=advertisers/advertiserId

مزيد من الأمثلة على استخدام مَعلمة الحقول

تتضمّن الأمثلة أدناه أوصافًا توضّح كيفية استخدام قيمة مَعلمة fields. يؤثر على الاستجابة.

ملاحظة: كما هو الحال مع جميع قيم مَعلمات طلب البحث، يجب أن تكون قيمة مَعلمة fields تم ترميز عنوان URL. لتسهيل القراءة، تتجاهل الأمثلة الواردة في هذا المستند الترميز.

حدِّد الحقول التي تريد عرضها أو اختَر اختيارات الحقول.

قيمة معلَمة طلب fields هي قائمة من الحقول مفصولة بفواصل. يتم تحديد كل حقل نسبةً إلى جذر الاستجابة. وبالتالي، إذا تجري عملية list، ويكون الرد مجموعة، تتضمن بشكل عام صفيفة من الموارد. في حال كنت تجري عملية يعرض موردًا واحدًا، يتم تحديد الحقول ذات الصلة بذلك المصدر. إذا كان الحقل الذي تحدده هو صفيف (أو يمثل جزءًا منه)، فإن الخادم تؤدي إلى إرجاع الجزء المحدد من جميع العناصر في الصفيفة.

في ما يلي بعض الأمثلة على مستوى المجموعة:

مثال	التأثير
advertisers	لعرض كافة العناصر في مصفوفة advertisers، بما في ذلك جميع الحقول في كل عنصر، ولكن وليس حقول أخرى.
advertisers,nextPageToken	تؤدي إلى عرض كلّ من nextPageToken وجميع العناصر الموجودة في مصفوفة advertisers
advertisers/advertiserId	لا تعرض سوى advertiserId. لجميع العناصر في مصفوفة advertisers عندما يكون الحقل المتداخل تم إرجاعها، يتضمن الرد الكائنات الرئيسية المرفقة. لا تتضمن الحقول الرئيسية أي حقول فرعية أخرى ما لم تم اختيارهم أيضًا بشكل صريح.
advertisers/generalConfig/domainUrl	عرض الحقل domainUrl للكائن generalConfig، والذي يتم دمجه نفسه ضمن مصفوفة advertisers

وفي ما يلي بعض الأمثلة على مستوى الموارد:

مثال	التأثير
advertiserId	عرض الحقل advertiserId للمورد المطلوب.
generalConfig/domainUrl	عرض الحقل domainUrl للكائن generalConfig في المورد المطلوب.

اطلب فقط أجزاءً من حقولاً معيّنة باستخدام الاختيارات الفرعية.

بشكل افتراضي، إذا كان طلبك يحدد حقولاً معينة، يعرض الخادم الكائنات أو عناصر الصفيفة بالكامل. يمكنك تحديد ردّ التي تتضمن حقولاً فرعية معينة فقط. يمكنك إجراء ذلك باستخدام "( )" بناء جملة التحديد الفرعي، كما في المثال أدناه.

مثال	التأثير
advertisers(advertiserId,generalConfig/domainUrl)	لا تعرض سوى قِيم advertiserId وGeneralConfig domainUrl مقابل كل عنصر في advertisers صفيفة.

التعامل مع الردود الجزئية

بعد أن يعالج الخادم طلبًا صالحًا يتضمّن طلب البحث fields فإنها تُعيد إرسال رمز حالة HTTP 200 OK، مع البيانات. إذا كانت معلَمة طلب البحث fields بها خطأ أو كانت غير صالحة، سيتم يعرض الخادم رمز حالة HTTP 400 Bad Request، مع ظهور خطأ تخبرك بالخطأ في تحديد الحقول (على سبيل المثال، "Invalid field selection a/b").

ملاحظة: لواجهات برمجة التطبيقات التي تتيح معلَمات طلب البحث لتقسيم البيانات على صفحات (maxResults وnextPageToken، على سبيل المثال)، استخدم هذه المعلمات لتقليل النتائج من كل استعلام بحجم يمكن إدارته. وإلا، ستحقق المكاسب المحتملة مع استجابة جزئية.