نکات عملکردی

این سند برخی از تکنیک‌هایی را که می‌توانید برای بهبود عملکرد برنامه خود استفاده کنید، پوشش می‌دهد. در برخی موارد، از مثال‌هایی از APIهای دیگر یا APIهای عمومی برای نشان دادن ایده‌های ارائه شده استفاده شده است. با این حال، همین مفاهیم برای API کتابخانه Google Photos نیز قابل اجرا هستند.

فشرده‌سازی با استفاده از gzip

یک راه آسان و راحت برای کاهش پهنای باند مورد نیاز برای هر درخواست، فعال کردن فشرده‌سازی gzip است. اگرچه این کار به زمان اضافی CPU برای خارج کردن نتایج از حالت فشرده نیاز دارد، اما معمولاً با توجه به هزینه‌های شبکه، ارزش انجام آن را دارد.

برای دریافت پاسخی که با gzip کدگذاری شده است، باید دو کار انجام دهید: یک هدر Accept-Encoding تنظیم کنید و عامل کاربر خود را طوری تغییر دهید که شامل رشته gzip باشد. در اینجا مثالی از هدرهای HTTP که به درستی شکل گرفته‌اند برای فعال کردن فشرده‌سازی gzip آورده شده است:

Accept-Encoding: gzip
User-Agent: my program (gzip)

کار با منابع جزئی

راه دیگر برای بهبود عملکرد فراخوانی‌های API شما، درخواست فقط بخشی از داده‌هایی است که به آنها علاقه‌مند هستید. این به برنامه شما اجازه می‌دهد از انتقال، تجزیه و ذخیره فیلدهای غیرضروری جلوگیری کند، بنابراین می‌تواند از منابعی از جمله شبکه، CPU و حافظه به طور مؤثرتری استفاده کند.

پاسخ جزئی

به طور پیش‌فرض، سرور پس از پردازش درخواست‌ها، نمایش کامل یک منبع را ارسال می‌کند. برای عملکرد بهتر، می‌توانید از سرور بخواهید که فقط فیلدهایی را که واقعاً به آنها نیاز دارید ارسال کند و در عوض، پاسخی جزئی دریافت کنید.

برای درخواست پاسخ جزئی، از پارامتر درخواست fields برای مشخص کردن فیلدهایی که می‌خواهید برگردانده شوند استفاده کنید. می‌توانید از این پارامتر با هر درخواستی که داده‌های پاسخ را برمی‌گرداند، استفاده کنید.

مثال

مثال زیر استفاده از پارامتر fields را با یک API عمومی (تخیلی) "Demo" نشان می‌دهد.

درخواست ساده: این درخواست HTTP GET پارامتر fields را حذف کرده و منبع کامل را برمی‌گرداند.

https://www.googleapis.com/demo/v1

پاسخ کامل منبع: داده‌های کامل منبع شامل فیلدهای زیر به همراه بسیاری دیگر است که به دلیل اختصار حذف شده‌اند.

{
  "kind": "demo",
  ...
  "items": [
  {
    "title": "First title",
    "comment": "First comment.",
    "characteristics": {
      "length": "short",
      "accuracy": "high",
      "followers": ["Jo", "Will"],
    },
    "status": "active",
    ...
  },
  {
    "title": "Second title",
    "comment": "Second comment.",
    "characteristics": {
      "length": "long",
      "accuracy": "medium"
      "followers": [ ],
    },
    "status": "pending",
    ...
  },
  ...
  ]
}

درخواست برای پاسخ جزئی: درخواست زیر برای همین منبع از پارامتر fields برای کاهش قابل توجه میزان داده‌های برگشتی استفاده می‌کند.

https://www.googleapis.com/demo/v1?fields=kind,items(title,characteristics/length)

پاسخ جزئی: در پاسخ به درخواست بالا، سرور پاسخی را ارسال می‌کند که فقط شامل اطلاعات نوع به همراه یک آرایه آیتم خلاصه شده است که فقط شامل عنوان HTML و اطلاعات مشخصه طول در هر آیتم است.

200 OK

{
  "kind": "demo",
  "items": [{
    "title": "First title",
    "characteristics": {
      "length": "short"
    }
  }, {
    "title": "Second title",
    "characteristics": {
      "length": "long"
    }
  },
  ...
  ]
}

توجه داشته باشید که پاسخ یک شیء JSON است که فقط شامل فیلدهای انتخاب شده و اشیاء والد محصور کننده آنها می‌شود.

جزئیات مربوط به نحوه قالب‌بندی پارامتر fields در ادامه پوشش داده شده است، و پس از آن جزئیات بیشتری در مورد آنچه دقیقاً در پاسخ بازگردانده می‌شود، ارائه شده است.

خلاصه سینتکس پارامتر فیلدها

قالب مقدار پارامتر درخواست fields تا حدودی مبتنی بر سینتکس XPath است. سینتکس پشتیبانی شده در زیر خلاصه شده است و مثال‌های اضافی در بخش بعدی ارائه شده است.

• برای انتخاب چندین فیلد، از یک لیست جدا شده با کاما استفاده کنید.
• a/b برای انتخاب فیلد b که درون فیلد a قرار دارد استفاده کنید؛ a/b/c برای انتخاب فیلد c که درون b قرار دارد استفاده کنید.
  

  استثنا: برای پاسخ‌های API که از پوشش‌های "data" استفاده می‌کنند، که در آن پاسخ درون یک شیء data که شبیه data: { ... } است، قرار می‌گیرد، " data " را در مشخصات fields وارد نکنید. وارد کردن شیء داده با مشخصات فیلدهایی مانند data/a/b باعث خطا می‌شود. در عوض، فقط از مشخصات fields مانند a/b استفاده کنید.

• با قرار دادن عبارات درون پرانتز " ( ) " از یک زیر-انتخابگر برای درخواست مجموعه‌ای از زیر-فیلدهای خاص از آرایه‌ها یا اشیاء استفاده کنید.

  برای مثال: fields=items(id,author/email) فقط شناسه آیتم و ایمیل نویسنده را برای هر عنصر در آرایه items برمی‌گرداند. همچنین می‌توانید یک زیرفیلد مشخص کنید، که در آن fields=items(id) معادل fields=items/id است.

• در صورت نیاز، در انتخاب فیلدها از کاراکترهای عمومی (wildcards) استفاده کنید.

  برای مثال: fields=items/pagemap/* تمام اشیاء موجود در یک نقشه صفحه را انتخاب می‌کند.

مثال‌های بیشتر از استفاده از پارامتر fields

مثال‌های زیر شامل توضیحاتی در مورد چگونگی تأثیر مقدار پارامتر fields بر پاسخ است.

توجه: همانند تمام مقادیر پارامترهای پرس‌وجو، مقدار پارامتر fields باید به صورت URL کدگذاری شود. برای خوانایی بهتر، مثال‌های این سند از کدگذاری صرف نظر کرده‌اند.

فیلدهایی را که می‌خواهید برگردانده شوند، شناسایی کنید یا انتخاب‌های فیلدی انجام دهید.

مقدار پارامتر درخواست fields ، فهرستی از فیلدها است که با کاما از هم جدا شده‌اند و هر فیلد نسبت به ریشه پاسخ مشخص می‌شود. بنابراین، اگر شما در حال انجام یک عملیات فهرست‌سازی هستید، پاسخ یک مجموعه است و عموماً شامل آرایه‌ای از منابع است. اگر در حال انجام عملیاتی هستید که یک منبع واحد را برمی‌گرداند، فیلدها نسبت به آن منبع مشخص می‌شوند. اگر فیلدی که انتخاب می‌کنید (یا بخشی از) یک آرایه باشد، سرور بخش انتخاب شده از تمام عناصر موجود در آرایه را برمی‌گرداند.

در اینجا چند مثال در سطح مجموعه آورده شده است:

مثال‌ها	اثر
items	تمام عناصر موجود در آرایه items، شامل تمام فیلدهای هر عنصر، اما بدون فیلدهای دیگر را برمی‌گرداند.
etag,items	هم فیلد etag و هم تمام عناصر موجود در آرایه items را برمی‌گرداند.
items/title	فقط فیلد title را برای همه عناصر موجود در آرایه items برمی‌گرداند. هر زمان که یک فیلد تو در تو برگردانده شود، پاسخ شامل اشیاء والدِ در برگیرنده آن نیز می‌شود. فیلدهای والد شامل هیچ فیلد فرزند دیگری نمی‌شوند، مگر اینکه آنها نیز به صراحت انتخاب شوند.
context/facets/label	فقط فیلد label را برای همه اعضای آرایه facets برمی‌گرداند، که خود زیر شیء context قرار دارد.
items/pagemap/*/title	برای هر عنصر در آرایه items، فقط فیلد title (در صورت وجود) تمام اشیاء فرزند pagemap برمی‌گرداند.

در اینجا چند مثال در سطح منابع آورده شده است:

مثال‌ها	اثر
title	فیلد title منبع درخواستی را برمی‌گرداند.
author/uri	زیرفیلد uri مربوط به شیء author در منبع درخواستی را برمی‌گرداند.
links/*/href	فیلد href تمام اشیاء فرزند links را برمی‌گرداند.

فقط بخش‌هایی از فیلدهای خاص را با استفاده از زیرگزینه‌ها درخواست کنید.

به طور پیش‌فرض، اگر درخواست شما فیلدهای خاصی را مشخص کند، سرور اشیاء یا عناصر آرایه را به طور کامل برمی‌گرداند. می‌توانید پاسخی را مشخص کنید که فقط شامل زیرفیلدهای خاصی باشد. این کار را با استفاده از سینتکس زیر-انتخاب " ( ) " انجام می‌دهید، مانند مثال زیر.

مثال	اثر
items(title,author/uri)	فقط مقادیر title و uri نویسنده را برای هر عنصر در آرایه items برمی‌گرداند.

مدیریت پاسخ‌های جزئی

پس از اینکه سرور یک درخواست معتبر که شامل پارامتر جستجوی fields است را پردازش می‌کند، یک کد وضعیت HTTP 200 OK را به همراه داده‌های درخواستی ارسال می‌کند. اگر پارامتر جستجوی fields دارای خطا باشد یا به هر دلیلی نامعتبر باشد، سرور یک کد وضعیت HTTP 400 Bad Request را به همراه یک پیام خطا که به کاربر می‌گوید چه مشکلی در انتخاب فیلدهای او وجود دارد، برمی‌گرداند (برای مثال، "Invalid field selection a/b" ).

در اینجا مثالی از پاسخ جزئی که در بخش مقدماتی بالا نشان داده شده است، آمده است. درخواست از پارامتر fields برای مشخص کردن فیلدهایی که باید برگردانده شوند، استفاده می‌کند.

https://www.googleapis.com/demo/v1?fields=kind,items(title,characteristics/length)

پاسخ جزئی به این شکل است:

200 OK

{
  "kind": "demo",
  "items": [{
    "title": "First title",
    "characteristics": {
      "length": "short"
    }
  }, {
    "title": "Second title",
    "characteristics": {
      "length": "long"
    }
  },
  ...
  ]
}

نکته: برای APIهایی که از پارامترهای پرس‌وجو برای صفحه‌بندی داده‌ها پشتیبانی می‌کنند (مثلاً maxResults و nextPageToken )، از این پارامترها برای کاهش نتایج هر پرس‌وجو به اندازه‌ای قابل مدیریت استفاده کنید. در غیر این صورت، ممکن است افزایش عملکرد ممکن با پاسخ جزئی محقق نشود.