اعتبارًا من 8 سبتمبر 2025، يجب أن يحدّد كل عنصر جديد في الحملة ما إذا كان سيعرض إعلانات سياسية في الاتحاد الأوروبي أم لا. ستتعذّر عمليات تحميل واجهة برمجة التطبيقات "مساحة العرض والفيديو 360" وملفات SDF التي لا تقدّم بيانات الإفصاح. يمكنك الاطّلاع على صفحة الإيقاف النهائي لمزيد من التفاصيل حول كيفية تعديل عملية الدمج لإجراء هذا البيان.
تنظيم صفحاتك في مجموعات
يمكنك حفظ المحتوى وتصنيفه حسب إعداداتك المفضّلة.
يتناول هذا المستند بعض الأساليب التي يمكنك استخدامها لتحسين أداء
تطبيقك. في بعض الحالات، يتم استخدام أمثلة من واجهات برمجة تطبيقات أخرى تم تنفيذها
لتوضيح الأفكار المقدَّمة. ومع ذلك، تنطبق المفاهيم نفسها
على Display & Video 360 API.
العمل مع موارد جزئية
هناك طريقة أخرى لتحسين أداء طلبات البيانات من واجهة برمجة التطبيقات، وهي طلب
الجزء من البيانات الذي يهمّك فقط. يتيح ذلك لتطبيقك
تجنُّب نقل الحقول غير المطلوبة وتحليلها وتخزينها، حتى يتمكّن من استخدام
الموارد مثل الشبكة ووحدة المعالجة المركزية والذاكرة بكفاءة أكبر.
ردّ جزئي
يُرسِل الخادم تلقائيًا التمثيل الكامل لمورد بعد
معالجة الطلبات. للحصول على أداء أفضل، يمكنك أن تطلب من الخادم إرسال
الحقول التي تحتاج إليها فقط والحصول على استجابة جزئية بدلاً من ذلك.
لطلب استجابة جزئية، استخدِم مَعلمة الطلب fields لتحديد
الحقول التي تريد عرضها. يمكنك استخدام هذه المَعلمة مع أي طلب
يعرض بيانات استجابة.
مثال
يوضّح المثال التالي استخدام المَعلمة fields مع
Display & Video 360 API.
طلب بسيط: يحذف طلب HTTP GET هذا المَعلمة fields ويُعيد
المورد الكامل.
GET https://displayvideo.googleapis.com/v4/advertisers?partnerId=1
استجابة المورد الكاملة: تتضمّن بيانات المورد الكاملة الحقلَين التاليَين، بالإضافة إلى العديد من الحقول الأخرى التي تم حذفها لأسباب تتعلق بالإيجاز.
طلب استجابة جزئية: يستخدم الطلب التالي للمورد نفسه
المَعلمة fields لتقليل كمية البيانات المعروضة بشكل كبير.
GET https://displayvideo.googleapis.com/v4/advertisers?partnerId=1&fields=advertisers(advertiserId,partnerId,displayName)
استجابة جزئية: استجابةً للطلب أعلاه، يُرسِل الخادم بدوره
استجابة تتضمّن صفيفًا مُبسّطًا للمعلِنين لا يتضمّن سوى
رقم تعريف المعلِن والاسم المعروض وسمة رقم تعريف الشريك لكل معلِن، إذا كانت
متوفّرة.
تجدر الإشارة إلى أنّ الاستجابة هي عنصر 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 هي قائمة بالحقول مفصولة بفواصل، ويتم تحديد كل حقل بالنسبة إلى جذر الاستجابة. وبالتالي، إذا كنت
تُجري عملية 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").
تاريخ التعديل الأخير: 2025-07-25 (حسب التوقيت العالمي المتفَّق عليه)
[null,null,["تاريخ التعديل الأخير: 2025-07-25 (حسب التوقيت العالمي المتفَّق عليه)"],[[["\u003cp\u003eThis document explains how to improve your application's performance by fetching only the necessary data using partial responses.\u003c/p\u003e\n"],["\u003cp\u003ePartial responses are achieved using the \u003ccode\u003efields\u003c/code\u003e parameter in your API requests, letting you specify the desired fields to be returned.\u003c/p\u003e\n"],["\u003cp\u003eThe \u003ccode\u003efields\u003c/code\u003e parameter utilizes a syntax similar to XPath, allowing you to select specific fields, nested fields, and sub-fields within objects and arrays.\u003c/p\u003e\n"],["\u003cp\u003eWhen using the \u003ccode\u003efields\u003c/code\u003e parameter, the server returns a 200 OK status with the requested data or a 400 Bad Request if the parameter is invalid.\u003c/p\u003e\n"],["\u003cp\u003eFor APIs with pagination, combine the \u003ccode\u003efields\u003c/code\u003e parameter with \u003ccode\u003emaxResults\u003c/code\u003e and \u003ccode\u003enextPageToken\u003c/code\u003e to further optimize data retrieval and enhance performance.\u003c/p\u003e\n"]]],["To enhance API call performance, request only necessary data using the `fields` parameter for a partial response. This reduces data transfer, parsing, and storage, optimizing network, CPU, and memory usage. The `fields` parameter specifies desired fields in a comma-separated list, supporting nested field selection with `a/b` and sub-selections using `( )`. The server returns an HTTP 200 OK status with the specified data or 400 Bad Request if there is an error with the parameter.\n"],null,["# Improve Performance\n\nThis document covers some techniques you can use to improve the performance of\nyour application. In some cases, examples from other implemented APIs are used\nto illustrate the ideas presented. However, the same concepts are applicable\nto the Display \\& Video 360 API.\n\nWorking with partial resources\n------------------------------\n\nAnother way to improve the performance of your API calls is to request only\nthe portion of the data that you're interested in. This lets your application\navoid transferring, parsing, and storing unneeded fields, so it can use\nresources such as network, CPU, and memory more efficiently.\n\n### Partial response\n\nBy default, the server sends back the full representation of a resource after\nprocessing requests. For better performance, you can ask the server to send\nonly the fields you really need and get a *partial response* instead.\n\nTo request a partial response, use the `fields` request parameter to specify\nthe fields you want returned. You can use this parameter with any request\nthat returns response data.\n\n#### Example\n\nThe following example shows the use of the `fields` parameter with the\nDisplay \\& Video 360 API.\n\n**Simple request:** This HTTP `GET` request omits the `fields` parameter and\nreturns the full resource. \n\n GET https://displayvideo.googleapis.com/v4/advertisers?partnerId=1\n\n**Full resource response:** The full resource data includes the following\nfields, along with many others that have been omitted for brevity. \n\n 200 OK\n\n {\n \"advertisers\": [\n {\n \"name\": \"advertisers/1\",\n \"advertiserId\": \"1\",\n \"partnerId\": \"1\",\n \"displayName\": \"Example Advertiser 1\",\n \"entityStatus\": \"ENTITY_STATUS_ACTIVE\",\n \"updateTime\": \"2019-01-01T00:00:00.000000Z\",\n \"generalConfig\": {\n \"domainUrl\": \"http://example.com\",\n \"timeZone\": \"America/New_York\",\n \"currencyCode\": \"USD\",\n \"address\": {\n }\n },\n \"adServerConfig\": {\n \"thirdPartyOnlyConfig\": {\n }\n },\n \"creativeConfig\": {\n },\n \"dataAccessConfig\": {\n \"sdfConfig\": {\n \"sdfConfig\": {\n \"version\": \"VERSION_3_1\"\n }\n }\n },\n \"integrationDetails\": {\n }\n },\n {\n \"name\": \"advertisers/2\",\n \"advertiserId\": \"2\",\n \"partnerId\": \"1\",\n \"displayName\": \"Example Advertiser 2\",\n \"entityStatus\": \"ENTITY_STATUS_ACTIVE\",\n \"updateTime\": \"2019-01-01T00:00:00.000000Z\",\n \"generalConfig\": {\n \"domainUrl\": \"http://example.com\",\n \"timeZone\": \"America/New_York\",\n \"currencyCode\": \"USD\",\n \"address\": {\n }\n },\n \"adServerConfig\": {\n \"thirdPartyOnlyConfig\": {\n }\n },\n \"creativeConfig\": {\n },\n \"dataAccessConfig\": {\n \"sdfConfig\": {\n \"sdfConfig\": {\n \"version\": \"VERSION_3_1\"\n }\n }\n },\n \"integrationDetails\": {\n }\n },\n ...\n ],\n \"nextPageToken\": \"...\"\n }\n\n**Request for a partial response:** The following request for this same resource\nuses the `fields` parameter to significantly reduce the amount of data returned. \n\n```text\nGET https://displayvideo.googleapis.com/v4/advertisers?partnerId=1&fields=advertisers(advertiserId,partnerId,displayName)\n```\n\n**Partial response:** In response to the request above, the server sends back a\nresponse that contains a pared-down advertisers array that includes only the\nadvertiser ID, display name, and partner ID property of each advertiser, if\npresent. \n\n 200 OK\n\n {\n \"advertisers\": [\n {\n \"advertiserId\": \"1\",\n \"partnerId\": \"1\",\n \"displayName\": \"Example Advertiser 1\"\n },\n {\n \"advertiserId\": \"2\",\n \"partnerId\": \"1\",\n \"displayName\": \"Example Advertiser 2\"\n },\n ...\n ]\n }\n\nNote that the response is a JSON object that includes only the selected fields\nand their enclosing parent objects.\n\nDetails on how to format the `fields` parameter is covered next, followed by\nmore details about what exactly gets returned in the response.\n\n##### Fields parameter syntax summary\n\nThe format of the `fields` request parameter value is loosely based on XPath\nsyntax. The supported syntax is summarized below, and additional examples are\nprovided in the following section.\n\n- Use a comma-separated list to select multiple fields.\n\n- Use `a/b` to select a field `b` that is nested within field `a`; use `a/b/c`\n to select a field `c` nested within `b`.\n\n- Use a sub-selector to request a set of specific sub-fields of arrays or\n objects by placing expressions in parentheses \"`( )`\".\n\n For example: `fields=advertisers(advertiserId,generalConfig/domainUrl)`\n returns only the advertiser ID and domain URL for each element in the\n advertisers array. You can also specify a single sub-field, where\n `fields=advertisers(advertiserId)` is equivalent to\n `fields=advertisers/advertiserId`.\n\n##### More examples of using the fields parameter\n\nThe examples below include descriptions of how the `fields` parameter value\naffects the response.\n| **Note:** As with all query parameter values, the `fields` parameter value must be URL encoded. For better readability, the examples in this document omit the encoding.\n\nIdentify the fields you want returned, or make *field selections*.\n\n: The `fields` request parameter value is a comma-separated list of fields, and\n each field is specified relative to the root of the response. Thus, if you\n are performing a `list` operation, the response is a collection, and it\n generally includes an array of resources. If you are performing an operation\n that returns a single resource, fields are specified relative to that\n resource. If the field you select is (or is part of) an array, the server\n returns the selected portion of all elements in the array.\n\n Here are some collection-level examples:\n\n | Example | Effect |\n |---------------------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|\n | `advertisers` | Returns all elements in the `advertisers` array, including all fields in each element, but no other fields. |\n | `advertisers,nextPageToken` | Returns both the `nextPageToken` field and all elements in the `advertisers` array. |\n | `advertisers/advertiserId` | Returns only the `advertiserId` for all elements in the `advertisers` array. Whenever a nested field is returned, the response includes the enclosing parent objects. The parent fields do not include any other child fields unless they are also selected explicitly. |\n | `advertisers/generalConfig/domainUrl` | Returns the `domainUrl` field for the `generalConfig` object, which itself is nested under the `advertisers` array. |\n\n Here are some resource-level examples:\n\n | Example | Effect |\n |---------------------------|-----------------------------------------------------------------------------------------|\n | `advertiserId` | Returns the `advertiserId` field of the requested resource. |\n | `generalConfig/domainUrl` | Returns the `domainUrl` field for the `generalConfig` object in the requested resource. |\n\nRequest only parts of specific fields using *sub-selections*.\n\n: By default, if your request specifies particular fields, the server returns\n the objects or array elements in their entirety. You can specify a response\n that includes only certain sub-fields. You do this using \"`( )`\"\n sub-selection syntax, as in the example below.\n\n | Example | Effect |\n |-----------------------------------------------------|----------------------------------------------------------------------------------------------------------------------|\n | `advertisers(advertiserId,generalConfig/domainUrl)` | Returns only the values of `advertiserId` and generalConfig `domainUrl` for each element in the `advertisers` array. |\n\n##### Handling partial responses\n\nAfter a server processes a valid request that includes the `fields` query\nparameter, it sends back an HTTP `200 OK` status code, along with the requested\ndata. If the `fields` query parameter has an error or is otherwise invalid, the\nserver returns an HTTP `400 Bad Request` status code, along with an error\nmessage telling you what was wrong with the fields selection (for example,\n`\"Invalid field selection a/b\"`).\n| **Note:** For APIs that support query parameters for data pagination (`maxResults` and `nextPageToken`, for example), use those parameters to reduce the results of each query to a manageable size. Otherwise, the performance gains possible with partial response might not be realized."]]
