از 8 سپتامبر 2025 ، هر مورد خط جدید باید اعلام کند که آیا تبلیغات سیاسی اتحادیه اروپا (EU) را ارائه می دهد یا خیر. Display & Video 360 API و بارگذاری‌های SDF که اعلان‌ها را ارائه نمی‌کنند با شکست مواجه می‌شوند. برای جزئیات بیشتر در مورد نحوه به روز رسانی یکپارچه سازی خود برای ایجاد این اعلامیه، به صفحه لغو اعتبار ما مراجعه کنید.
با مجموعهها، منظم بمانید
ذخیره و طبقهبندی محتوا براساس اولویتهای شما.
این سند برخی از تکنیک ها را پوشش می دهد که می توانید برای بهبود عملکرد برنامه خود از آنها استفاده کنید. در برخی موارد، از نمونه هایی از دیگر APIهای پیاده سازی شده برای نشان دادن ایده های ارائه شده استفاده می شود. با این حال، همان مفاهیم برای Display & Video 360 API قابل اعمال است.
کار با منابع جزئی
یکی دیگر از راه‌های بهبود عملکرد تماس‌های API این است که فقط بخشی از داده‌هایی را که به آن علاقه دارید درخواست کنید. این به برنامه شما امکان می‌دهد از انتقال، تجزیه و ذخیره فیلدهای غیرضروری جلوگیری کند، بنابراین می‌تواند از منابعی مانند شبکه، CPU و حافظه به طور موثرتری استفاده کند.
پاسخ نسبی
به طور پیش فرض، سرور پس از پردازش درخواست ها، نمایش کامل یک منبع را پس می فرستد. برای عملکرد بهتر، می‌توانید از سرور بخواهید فقط فیلدهایی را که واقعاً به آن نیاز دارید ارسال کند و در عوض پاسخی جزئی دریافت کنید.
برای درخواست پاسخ جزئی، از پارامتر درخواست 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 لیستی از فیلدها است که با کاما از هم جدا شده اند و هر فیلد نسبت به ریشه پاسخ مشخص می شود. بنابراین، اگر شما یک عملیات 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" ) برمی گرداند.
تاریخ آخرین بهروزرسانی 2025-07-24 بهوقت ساعت هماهنگ جهانی.
[null,null,["تاریخ آخرین بهروزرسانی 2025-07-24 بهوقت ساعت هماهنگ جهانی."],[[["\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."]]
