نکات عملکرد

این سند برخی از تکنیک ها را پوشش می دهد که می توانید برای بهبود عملکرد برنامه خود از آنها استفاده کنید. در برخی موارد، نمونه هایی از سایر APIها یا APIهای عمومی برای نشان دادن ایده های ارائه شده استفاده می شود. با این حال، همان مفاهیم برای Google Civic Information API قابل اعمال است.

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

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

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

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

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

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

پاسخ نسبی

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

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

مثال

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

درخواست ساده: این درخواست 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 » را در مشخصات fields لحاظ نکنید. گنجاندن شی داده با مشخصات فیلدهایی مانند data/a/b باعث ایجاد خطا می شود. در عوض، فقط از مشخصات fields مانند a/b استفاده کنید.

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

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

• در صورت نیاز از حروف عام در انتخاب زمینه استفاده کنید.

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

نمونه های بیشتری از استفاده از پارامتر فیلدها

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

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

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

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

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

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

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

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

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

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

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

رسیدگی به پاسخ های جزئی

پس از اینکه سرور یک درخواست معتبر که شامل پارامتر پرس و جو fields است را پردازش کرد، یک کد وضعیت HTTP 200 OK را به همراه داده های درخواستی ارسال می کند. اگر پارامتر پرس و جو fields دارای خطا باشد یا در غیر این صورت نامعتبر باشد، سرور یک کد وضعیت 400 Bad Request را به همراه یک پیام خطایی که به کاربر می‌گوید در انتخاب فیلدهایش چه مشکلی داشته است (به عنوان مثال، "Invalid field selection a/b" . "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 )، از این پارامترها برای کاهش نتایج هر پرس و جو به اندازه قابل مدیریت استفاده کنید. در غیر این صورت، افزایش عملکرد ممکن با پاسخ نسبی ممکن است محقق نشود.