تحسين الأداء

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

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

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

ردّ جزئي

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

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

مثال

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

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

GET https://displayvideo.googleapis.com/v4/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/v4/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 في الاستجابة.

ملاحظة: كما هو الحال مع جميع قيم مَعلمات طلب البحث، يجب أن تكون قيمة المَعلمة 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، بالإضافة إلى data المطلوبة. إذا كانت مَعلمة طلب البحث fields تتضمّن خطأً أو كانت غير صالحة، يعرض الخادم رمز حالة HTTP 400 Bad Request، بالإضافة إلى رسالة خطأ توضّح لك المشكلة في اختيار الحقول (على سبيل المثال، "Invalid field selection a/b").

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