با استفاده از API

مطالب

مقدمه

این سند برای توسعه دهندگانی است که می خواهند برنامه هایی بنویسند که بتوانند با Books API تعامل داشته باشند. Google Books ماموریت دارد تا محتوای کتاب جهان را دیجیتالی کند و آن را در وب بیشتر قابل کشف کند. Books API راهی برای جستجو و دسترسی به آن محتوا و همچنین ایجاد و مشاهده شخصی سازی پیرامون آن محتوا است.

اگر با مفاهیم Google Books آشنا نیستید، باید قبل از شروع به کدنویسی، شروع به کار را بخوانید.

تأیید درخواست ها و شناسایی درخواست شما

هر درخواستی که برنامه شما به Books API ارسال می کند باید برنامه شما را به Google شناسایی کند. دو راه برای شناسایی برنامه شما وجود دارد: استفاده از یک توکن OAuth 2.0 (که درخواست را نیز مجاز می کند) و/یا استفاده از کلید API برنامه. در اینجا نحوه تعیین اینکه کدام یک از این گزینه ها استفاده شود آورده شده است:

  • اگر درخواست نیاز به مجوز داشته باشد (مانند درخواست برای داده های خصوصی یک فرد)، برنامه باید یک توکن OAuth 2.0 را همراه با درخواست ارائه کند. برنامه ممکن است کلید API را نیز ارائه کند، اما لازم نیست.
  • اگر درخواست به مجوز نیاز ندارد (مانند درخواست برای داده‌های عمومی)، برنامه باید یا کلید API یا یک نشانه OAuth 2.0 یا هر دو را ارائه دهد - هر گزینه ای که برای شما راحت تر است.

درباره پروتکل های مجوز

برنامه شما باید از OAuth 2.0 برای تأیید درخواست ها استفاده کند. هیچ پروتکل مجوز دیگری پشتیبانی نمی شود. اگر برنامه شما از ورود به سیستم با Google استفاده می کند، برخی از جنبه های مجوز برای شما انجام می شود.

تأیید درخواست ها با OAuth 2.0

درخواست‌ها به Books API برای داده‌های کاربر غیرعمومی باید توسط یک کاربر تأیید شده مجاز باشد.

جزئیات فرآیند مجوز یا "جریان" برای OAuth 2.0 بسته به نوع برنامه ای که می نویسید تا حدودی متفاوت است. فرآیند کلی زیر برای همه انواع برنامه ها اعمال می شود:

  1. هنگامی که برنامه خود را ایجاد می کنید، آن را با استفاده از Google API Console ثبت می کنید. سپس Google اطلاعاتی را که بعداً به آن نیاز خواهید داشت، مانند شناسه مشتری و راز مشتری ارائه می دهد.
  2. Books API را در Google API Console فعال کنید. (اگر API در لیست API Console نیست، از این مرحله صرفنظر کنید.)
  3. هنگامی که برنامه شما نیاز به دسترسی به داده های کاربر دارد، از Google دامنه دسترسی خاصی را می خواهد.
  4. Google یک صفحه رضایت به کاربر نمایش می دهد و از او می خواهد تا به برنامه شما اجازه دهد تا برخی از داده های خود را درخواست کند.
  5. اگر کاربر تأیید کند، گوگل به برنامه شما یک رمز دسترسی کوتاه مدت می دهد.
  6. برنامه شما با پیوست کردن رمز دسترسی به درخواست، داده های کاربر را درخواست می کند.
  7. اگر Google تشخیص دهد که درخواست شما و رمز معتبر هستند، داده‌های درخواستی را برمی‌گرداند.

برخی از جریان‌ها شامل مراحل اضافی هستند، مانند استفاده از نشانه‌های تازه‌سازی برای به دست آوردن نشانه‌های دسترسی جدید. برای اطلاعات دقیق درباره جریان‌ها برای انواع مختلف برنامه‌ها، به اسناد OAuth 2.0 Google مراجعه کنید.

در اینجا اطلاعات محدوده OAuth 2.0 برای Books API آمده است:

https://www.googleapis.com/auth/books

برای درخواست دسترسی با استفاده از OAuth 2.0، برنامه شما به اطلاعات محدوده و همچنین اطلاعاتی که Google هنگام ثبت برنامه خود ارائه می دهد (مانند شناسه مشتری و رمز سرویس گیرنده) نیاز دارد.

نکته: کتابخانه های سرویس گیرنده Google APIs می توانند برخی از فرآیندهای مجوز را برای شما انجام دهند. آنها برای انواع زبان های برنامه نویسی در دسترس هستند. برای جزئیات بیشتر صفحه را با کتابخانه ها و نمونه ها بررسی کنید.

به دست آوردن و استفاده از یک کلید API

درخواست‌های Books API برای داده‌های عمومی باید همراه با یک شناسه باشد که می‌تواند یک کلید API یا یک نشانه دسترسی باشد.

برای به دست آوردن یک کلید API:

  1. صفحه Credentials را در کنسول API باز کنید.
  2. این API از دو نوع اعتبارنامه پشتیبانی می کند. هر اعتباری را که برای پروژه شما مناسب است ایجاد کنید:
    • OAuth 2.0: هر زمان که برنامه شما اطلاعات کاربر خصوصی را درخواست می کند، باید یک توکن OAuth 2.0 را همراه با درخواست ارسال کند. برنامه شما ابتدا یک شناسه مشتری و احتمالاً یک رمز سرویس گیرنده را برای دریافت رمز ارسال می کند. می توانید اعتبارنامه OAuth 2.0 را برای برنامه های کاربردی وب، حساب های خدماتی یا برنامه های نصب شده ایجاد کنید.

      برای اطلاعات بیشتر، به مستندات OAuth 2.0 مراجعه کنید.

    • کلیدهای API: درخواستی که توکن OAuth 2.0 ارائه نمی کند باید یک کلید API ارسال کند. کلید پروژه شما را شناسایی می کند و دسترسی، سهمیه و گزارش های API را فراهم می کند.

      API از چندین نوع محدودیت در کلیدهای API پشتیبانی می کند. اگر کلید API مورد نیاز شما از قبل وجود ندارد، با کلیک روی ایجاد اعتبار > کلید API، یک کلید API در کنسول ایجاد کنید. می‌توانید کلید را قبل از استفاده از آن در تولید با کلیک کردن روی Restrict key و انتخاب یکی از محدودیت‌ها محدود کنید.

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

بعد از اینکه یک کلید API داشتید، برنامه شما می تواند پارامتر query key= yourAPIKey به همه URL های درخواستی اضافه کند.

کلید API برای جاسازی در URL ها ایمن است. به هیچ کدگذاری نیاز ندارد.

شناسه‌های Google Books

باید فیلدهای شناسه را با فراخوانی‌های متد API خاص مشخص کنید. سه نوع شناسه در Google Books استفاده می شود:

  • شناسه‌های جلد - رشته‌های منحصربه‌فردی که به هر جلدی که Google Books درباره آن می‌داند داده می‌شود. نمونه ای از شناسه حجمی _LettPDhwR0C است. شما می توانید از API برای دریافت شناسه حجم با درخواستی که منبع حجم را برمی گرداند استفاده کنید. می توانید شناسه حجم را در قسمت id آن پیدا کنید.
  • شناسه های قفسه کتاب - مقادیر عددی داده شده به قفسه کتاب در کتابخانه کاربر. Google قفسه های از پیش تعریف شده ای را برای هر کاربر با شناسه های زیر ارائه می کند:
    • موارد مورد علاقه: 0
    • خریداری شده: 1
    • خواندن: 2
    • اکنون در حال خواندن: 3
    • خوانده اید: 4
    • بررسی شده: 5
    • بازدید اخیر: 6
    • کتاب های الکترونیکی من: 7
    • Books For You: 8 اگر هیچ توصیه ای برای کاربر نداریم، این قفسه وجود ندارد.
    قفسه های سفارشی دارای شناسه های بزرگتر از 1000 هستند. شناسه قفسه کتاب برای یک کاربر خاص منحصر به فرد است، به عنوان مثال، دو کاربر می توانند یک قفسه کتاب با شناسه یکسان داشته باشند که به قفسه های مختلف کتاب اشاره دارد. می‌توانید از API برای دریافت شناسه قفسه کتاب با درخواستی که منبع قفسه کتاب را برمی‌گرداند، استفاده کنید. می توانید شناسه قفسه کتاب را در قسمت id آن پیدا کنید.
  • شناسه های کاربر - مقادیر عددی منحصر به فرد اختصاص داده شده به هر کاربر. این مقادیر لزوماً همان مقدار ID مورد استفاده در سایر خدمات Google نیستند. در حال حاضر، تنها راه بازیابی شناسه کاربر، استخراج آن از selfLink در یک منبع Bookshelf است که با یک درخواست احراز هویت بازیابی شده است. کاربران همچنین می توانند شناسه کاربری خود را از سایت Books دریافت کنند. کاربر نمی تواند شناسه کاربری کاربر دیگری را از طریق API یا سایت Books بدست آورد. کاربر دیگر باید آن اطلاعات را بطور صریح به اشتراک بگذارد، مثلاً از طریق ایمیل.

شناسه ها در سایت Google Books

شناسه‌هایی که با Books API استفاده می‌کنید، همان شناسه‌هایی هستند که در سایت Google Books استفاده می‌شوند.

  • شناسه حجم

    هنگام مشاهده یک حجم خاص در سایت، می توانید شناسه حجم را در پارامتر id URL پیدا کنید. در اینجا یک مثال است:

    https://books.google.com/ebooks?id=buc0AAAAMAAJ&dq=holmes&as_brr=4&source=webstore_bookcard

  • شناسه قفسه کتاب

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

    https://books.google.com/books?hl=en&as_coll=0&num=10&uid=11122233344455566778&source=gbs_slider_cls_metadata_0_mylibrary

  • شناسه کاربری

    هنگام مشاهده کتابخانه خود در سایت، می توانید شناسه کاربری را در پارامتر URL uid پیدا کنید. در اینجا یک مثال است:

    https://books.google.com/books?uid=11122233344455566778&source=gbs_lp_bookshelf_list

تنظیم مکان کاربر

Google Books به حق نسخه‌برداری، قرارداد و سایر محدودیت‌های قانونی مرتبط با موقعیت مکانی کاربر نهایی احترام می‌گذارد. در نتیجه، برخی از کاربران ممکن است نتوانند به محتوای کتاب از برخی کشورها دسترسی داشته باشند. برای مثال، برخی کتاب‌ها فقط در ایالات متحده «قابل نمایش» هستند. ما چنین پیوندهای پیش نمایشی را برای کاربران کشورهای دیگر حذف می کنیم. بنابراین، نتایج API بر اساس آدرس IP سرور یا برنامه مشتری شما محدود می شود.

کار با حجم ها

انجام جستجو

می توانید با ارسال یک درخواست HTTP GET به URI زیر، جستجوی حجم انجام دهید:

https://www.googleapis.com/books/v1/volumes?q=search+terms

این درخواست دارای یک پارامتر مورد نیاز واحد است:

  • q - جست و جوی جلدهایی که حاوی این رشته متنی هستند. کلمات کلیدی خاصی وجود دارد که می توانید در عبارات جستجو برای جستجو در فیلدهای خاص مشخص کنید، مانند:
    • intitle: نتایجی را برمی‌گرداند که متن زیر این کلمه کلیدی در عنوان یافت می‌شود.
    • inauthor: نتایجی را برمی‌گرداند که متن زیر این کلمه کلیدی در نویسنده یافت می‌شود.
    • inpublisher: نتایجی را برمی‌گرداند که متن زیر این کلمه کلیدی در ناشر یافت می‌شود.
    • subject: نتایجی را برمی‌گرداند که متن زیر این کلمه کلیدی در فهرست دسته‌بندی جلد فهرست شده است.
    • isbn: نتایجی را برمی‌گرداند که متن زیر این کلمه کلیدی شماره شابک باشد.
    • lccn: نتایجی را برمی‌گرداند که متن زیر این کلمه کلیدی شماره کنترل کتابخانه کنگره باشد.
    • oclc: نتایجی را برمی‌گرداند که متن زیر این کلمه کلیدی شماره مرکز کتابخانه رایانه آنلاین باشد.

درخواست کنید

در اینجا نمونه ای از جستجوی «گل برای الجرنون» اثر دانیل کیز است:

GET https://www.googleapis.com/books/v1/volumes?q=flowers+inauthor:keyes&key=yourAPIKey

توجه: انجام جستجو نیازی به احراز هویت ندارد، بنابراین لازم نیست هدر HTTP Authorization با درخواست GET ارائه دهید. با این حال، اگر تماس با احراز هویت انجام شود، هر جلد شامل اطلاعات خاص کاربر، مانند وضعیت خریداری شده است.

پاسخ

اگر درخواست با موفقیت انجام شود، سرور با یک کد وضعیت HTTP 200 OK پاسخ می دهد و حجم صدا نتیجه می دهد:

200 OK

{
 "kind": "books#volumes",
 "items": [
  {
   "kind": "books#volume",
   "id": "_ojXNuzgHRcC",
   "etag": "OTD2tB19qn4",
   "selfLink": "https://www.googleapis.com/books/v1/volumes/_ojXNuzgHRcC",
   "volumeInfo": {
    "title": "Flowers",
    "authors": [
     "Vijaya Khisty Bodach"
    ],
   ...
  },
  {
   "kind": "books#volume",
   "id": "RJxWIQOvoZUC",
   "etag": "NsxMT6kCCVs",
   "selfLink": "https://www.googleapis.com/books/v1/volumes/RJxWIQOvoZUC",
   "volumeInfo": {
    "title": "Flowers",
    "authors": [
     "Gail Saunders-Smith"
    ],
    ...
  },
  {
   "kind": "books#volume",
   "id": "zaRoX10_UsMC",
   "etag": "pm1sLMgKfMA",
   "selfLink": "https://www.googleapis.com/books/v1/volumes/zaRoX10_UsMC",
   "volumeInfo": {
    "title": "Flowers",
    "authors": [
     "Paul McEvoy"
    ],
    ...
  },
  "totalItems": 3
}

پارامترهای پرس و جو اختیاری

علاوه بر پارامترهای پرس و جوی استاندارد ، می توانید هنگام انجام جستجوی حجمی از پارامترهای پرس و جو زیر استفاده کنید.

فرمت دانلود

epub با download به مقدار epub .

مثال زیر کتاب‌هایی را جستجو می‌کند که دانلود epub موجود است:

GET https://www.googleapis.com/books/v1/volumes?q=pride+prejudice&download=epub&key=yourAPIKey
فیلتر کردن

می توانید از پارامتر filter برای محدود کردن بیشتر نتایج بازگشتی با تنظیم آن بر روی یکی از مقادیر زیر استفاده کنید:

  • partial - نتایجی را برمی‌گرداند که حداقل قسمت‌هایی از متن قابل پیش‌نمایش باشد.
  • full - فقط نتایجی را برمی‌گرداند که تمام متن قابل مشاهده باشد.
  • free-ebooks - فقط نتایجی را برمی‌گرداند که کتاب‌های الکترونیکی رایگان Google هستند.
  • paid-ebooks - فقط نتایجی را که کتاب‌های الکترونیکی Google هستند را با قیمت برمی‌گرداند.
  • ebooks - فقط نتایجی را برمی‌گرداند که کتاب‌های الکترونیکی Google، پولی یا رایگان هستند. نمونه‌هایی از غیرکتاب‌های الکترونیکی محتوای ناشر است که در پیش‌نمایش محدود در دسترس است و برای فروش نیست، یا مجلات.

مثال زیر نتایج جستجو را به مواردی که به عنوان کتاب الکترونیکی رایگان در دسترس هستند محدود می کند:

GET https://www.googleapis.com/books/v1/volumes?q=flowers&filter=free-ebooks&key=yourAPIKey
صفحه بندی

می توانید با تعیین دو مقدار در پارامترهای درخواست، فهرست حجم ها را صفحه بندی کنید:

  • startIndex - موقعیتی در مجموعه که از آن شروع می شود. شاخص مورد اول 0 است.
  • maxResults - حداکثر تعداد نتایج برای بازگشت. پیش فرض 10 و حداکثر مقدار مجاز 40 است.

می‌توانید از پارامتر printType برای محدود کردن نتایج بازگشتی به یک نوع چاپ یا انتشار خاص با تنظیم آن بر روی یکی از مقادیر زیر استفاده کنید:

  • all - بر اساس نوع چاپ (پیش فرض) محدود نمی شود.
  • books - فقط نتایجی را که کتاب هستند برمی‌گرداند.
  • magazines - نتایجی را که مجلات هستند برمی گرداند.

مثال زیر نتایج جستجو را به مجلات محدود می کند:

GET https://www.googleapis.com/books/v1/volumes?q=time&printType=magazines&key=yourAPIKey
فرافکنی

می توانید از پارامتر projection با یکی از مقادیر زیر برای تعیین مجموعه از پیش تعریف شده از فیلدهای Volume برای بازگشت استفاده کنید:

  • full - همه فیلدهای حجم را برمی گرداند.
  • lite - فقط فیلدهای خاصی را برمی گرداند. توضیحات فیلد مشخص شده با ستاره دوتایی در مرجع حجم را ببینید تا متوجه شوید کدام فیلدها گنجانده شده اند.

مثال زیر نتایج جستجو را با اطلاعات حجم محدود برمی گرداند:

GET https://www.googleapis.com/books/v1/volumes?q=flowers&projection=lite&key=yourAPIKey
مرتب سازی

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

با تنظیم پارامتر orderBy به عنوان یکی از این مقادیر می توانید ترتیب را تغییر دهید:

  • relevance - نتایج را به ترتیب مرتبط بودن عبارات جستجو برمی گرداند (این حالت پیش فرض است).
  • newest - نتایج را به ترتیب جدیدترین تا حداقل اخیر منتشر شده برمی گرداند.

مثال زیر نتایج را بر اساس تاریخ انتشار، جدیدترین به قدیمی ترین فهرست می کند:

GET https://www.googleapis.com/books/v1/volumes?q=flowers&orderBy=newest&key=yourAPIKey

بازیابی یک حجم خاص

می توانید با ارسال یک درخواست HTTP GET به URI منبع حجم، اطلاعات یک حجم خاص را بازیابی کنید:

https://www.googleapis.com/books/v1/volumes/volumeId

پارامتر مسیر volumeId را با شناسه حجم برای بازیابی جایگزین کنید. برای اطلاعات بیشتر درباره شناسه‌های جلد، بخش شناسه‌های کتاب‌های Google را ببینید.

درخواست کنید

در اینجا نمونه ای از درخواست GET است که یک جلد دریافت می کند:

GET https://www.googleapis.com/books/v1/volumes/zyTCAlFPjgYC?key=yourAPIKey

توجه: بازیابی اطلاعات حجم نیازی به احراز هویت ندارد، بنابراین مجبور نیستید هدر HTTP Authorization با درخواست GET ارائه دهید. با این حال، اگر تماس با احراز هویت انجام شود، حجم شامل اطلاعات خاص کاربر، مانند وضعیت خرید می‌شود.

پاسخ

اگر درخواست با موفقیت انجام شود، سرور با کد وضعیت HTTP 200 OK و منبع حجم درخواست شده پاسخ می دهد:

200 OK

{
 "kind": "books#volume",
 "id": "zyTCAlFPjgYC",
 "etag": "f0zKg75Mx/I",
 "selfLink": "https://www.googleapis.com/books/v1/volumes/zyTCAlFPjgYC",
 "volumeInfo": {
  "title": "The Google story",
  "authors": [
   "David A. Vise",
   "Mark Malseed"
  ],
  "publisher": "Random House Digital, Inc.",
  "publishedDate": "2005-11-15",
  "description": "\"Here is the story behind one of the most remarkable Internet
  successes of our time. Based on scrupulous research and extraordinary access
  to Google, ...",
  "industryIdentifiers": [
   {
    "type": "ISBN_10",
    "identifier": "055380457X"
   },
   {
    "type": "ISBN_13",
    "identifier": "9780553804577"
   }
  ],
  "pageCount": 207,
  "dimensions": {
   "height": "24.00 cm",
   "width": "16.03 cm",
   "thickness": "2.74 cm"
  },
  "printType": "BOOK",
  "mainCategory": "Business & Economics / Entrepreneurship",
  "categories": [
   "Browsers (Computer programs)",
   ...
  ],
  "averageRating": 3.5,
  "ratingsCount": 136,
  "contentVersion": "1.1.0.0.preview.2",
  "imageLinks": {
   "smallThumbnail": "https://books.google.com/books?id=zyTCAlFPjgYC&printsec=frontcover&img=1&zoom=5&edge=curl&source=gbs_api",
   "thumbnail": "https://books.google.com/books?id=zyTCAlFPjgYC&printsec=frontcover&img=1&zoom=1&edge=curl&source=gbs_api",
   "small": "https://books.google.com/books?id=zyTCAlFPjgYC&printsec=frontcover&img=1&zoom=2&edge=curl&source=gbs_api",
   "medium": "https://books.google.com/books?id=zyTCAlFPjgYC&printsec=frontcover&img=1&zoom=3&edge=curl&source=gbs_api",
   "large": "https://books.google.com/books?id=zyTCAlFPjgYC&printsec=frontcover&img=1&zoom=4&edge=curl&source=gbs_api",
   "extraLarge": "https://books.google.com/books?id=zyTCAlFPjgYC&printsec=frontcover&img=1&zoom=6&edge=curl&source=gbs_api"
  },
  "language": "en",
  "infoLink": "https://books.google.com/books?id=zyTCAlFPjgYC&ie=ISO-8859-1&source=gbs_api",
  "canonicalVolumeLink": "https://books.google.com/books/about/The_Google_story.html?id=zyTCAlFPjgYC"
 },
 "saleInfo": {
  "country": "US",
  "saleability": "FOR_SALE",
  "isEbook": true,
  "listPrice": {
   "amount": 11.99,
   "currencyCode": "USD"
  },
  "retailPrice": {
   "amount": 11.99,
   "currencyCode": "USD"
  },
  "buyLink": "https://books.google.com/books?id=zyTCAlFPjgYC&ie=ISO-8859-1&buy=&source=gbs_api"
 },
 "accessInfo": {
  "country": "US",
  "viewability": "PARTIAL",
  "embeddable": true,
  "publicDomain": false,
  "textToSpeechPermission": "ALLOWED_FOR_ACCESSIBILITY",
  "epub": {
   "isAvailable": true,
   "acsTokenLink": "https://books.google.com/books/download/The_Google_story-sample-epub.acsm?id=zyTCAlFPjgYC&format=epub&output=acs4_fulfillment_token&dl_type=sample&source=gbs_api"
  },
  "pdf": {
   "isAvailable": false
  },
  "accessViewStatus": "SAMPLE"
 }
}
دسترسی به اطلاعات

بخش accessInfo برای تعیین اینکه چه ویژگی‌هایی برای کتاب الکترونیکی در دسترس است از اهمیت ویژه‌ای برخوردار است. epub یک کتاب الکترونیکی با فرمت متنی روان است، بخش epub دارای ویژگی isAvailable است که نشان می‌دهد این نوع کتاب الکترونیکی موجود است یا خیر. اگر نمونه ای از کتاب وجود داشته باشد یا کاربر بتواند کتاب را بخواند یا به دلیل خرید آن و یا به دلیل عمومی بودن آن در مکان کاربر، لینک دانلود خواهد داشت. یک pdf برای کتاب های گوگل یک نسخه صفحات اسکن شده از کتاب الکترونیکی را با جزئیات مشابه مانند موجود بودن و لینک دانلود نشان می دهد. گوگل فایل‌های epub را برای eReaders و گوشی‌های هوشمند توصیه می‌کند، زیرا ممکن است خواندن صفحات اسکن شده در این دستگاه‌ها سخت باشد. اگر بخش accessInfo وجود نداشته باشد، حجم به عنوان یک کتاب الکترونیکی Google در دسترس نیست.

پارامترهای پرس و جو اختیاری

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

فرافکنی

می توانید از پارامتر projection با یکی از مقادیر زیر برای تعیین مجموعه از پیش تعریف شده از فیلدهای Volume برای بازگشت استفاده کنید:

  • full - همه فیلدهای حجم را برمی گرداند.
  • lite - فقط فیلدهای خاصی را برمی گرداند. توضیحات فیلد مشخص شده با ستاره دوتایی در مرجع حجم را ببینید تا متوجه شوید کدام فیلدها گنجانده شده اند.

مثال زیر اطلاعات حجم محدودی را برای یک جلد برمی گرداند:

GET https://www.googleapis.com/books/v1/volumes/zyTCAlFPjgYC?projection=lite&key=yourAPIKey

کار با قفسه کتاب

بازیابی لیستی از قفسه های کتاب عمومی کاربر

می‌توانید با ارسال یک درخواست HTTP GET به URI با فرمت زیر، فهرستی از قفسه‌های کتاب عمومی کاربر را بازیابی کنید:

https://www.googleapis.com/books/v1/users/userId/bookshelves

پارامتر مسیر userId را با شناسه کاربری که می‌خواهید قفسه‌های کتاب او را بازیابی کنید، جایگزین کنید. برای اطلاعات بیشتر در مورد شناسه‌های کاربر، بخش شناسه‌های کتاب‌های Google را ببینید.

درخواست کنید

در اینجا یک مثال است:

GET https://www.googleapis.com/books/v1/users/1112223334445556677/bookshelves&key=yourAPIKey

از آنجایی که کاربر برای بازیابی اطلاعات مربوط به قفسه های عمومی نیازی به احراز هویت نیست، لازم نیست سرصفحه HTTP Authorization با درخواست GET ارائه دهید.

پاسخ

اگر درخواست موفق شد، سرور با کد وضعیت HTTP 200 OK و لیست قفسه‌های کتاب پاسخ می‌دهد:

200 OK

{
 "kind": "books#bookshelves",
 "items": [
  {
   ...
  },
  {
   "kind": "books#bookshelf",
   "id": 3,
   "selfLink": "https://www.googleapis.com/books/v1/users/1112223334445556677/bookshelves/3",
   "title": "Reading now",
   "description": "",
   "access": "PUBLIC",
   "updated": "2011-02-02T20:34:20.146Z",
   "created": "2011-02-02T20:34:20.146Z",
   "volumeCount": 2,
   "volumesLastUpdated": "2011-02-02T20:34:20.110Z"
  },
  ...
 ]
}

پارامترهای پرس و جو اختیاری

هنگام بازیابی لیست قفسه های کتاب عمومی کاربر، می توانید از پارامترهای پرس و جو استاندارد استفاده کنید.

بازیابی یک قفسه کتاب عمومی خاص

با ارسال یک درخواست HTTP GET به URI با فرمت زیر می‌توانید یک قفسه کتاب عمومی خاص را بازیابی کنید:

https://www.googleapis.com/books/v1/users/userId/bookshelves/shelf

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

درخواست کنید

در اینجا یک مثال است:

GET https://www.googleapis.com/books/v1/users/1112223334445556677/bookshelves/3?key=yourAPIKey

از آنجایی که کاربر برای بازیابی اطلاعات مربوط به قفسه های عمومی نیازی به احراز هویت نیست، لازم نیست سرصفحه HTTP Authorization با درخواست GET ارائه دهید.

پاسخ

اگر درخواست با موفقیت انجام شود، سرور با کد وضعیت HTTP 200 OK و منبع قفسه کتاب پاسخ می دهد:

200 OK

{
  "kind": "books#bookshelf",
  "id": 3,
  "selfLink": "https://www.googleapis.com/books/v1/users/1112223334445556677/bookshelves/3",
  "title": "Reading now",
  "description": "",
  "access": "PUBLIC",
  "updated": "2011-02-02T20:34:20.146Z",
  "created": "2011-02-02T20:34:20.146Z",
  "volumeCount": 2,
  "volumesLastUpdated": "2011-02-02T20:34:20.110Z"
}

پارامترهای پرس و جو اختیاری

هنگام بازیابی یک قفسه کتاب عمومی خاص می توانید از پارامترهای پرس و جوی استاندارد استفاده کنید.

بازیابی فهرستی از مجلدات در یک قفسه کتاب عمومی

با ارسال یک درخواست HTTP GET با فرمت زیر می‌توانید فهرستی از جلدها را در قفسه کتاب عمومی کاربر بازیابی کنید:

https://www.googleapis.com/books/v1/user/userId/bookshelves/shelf/volumes

درخواست کنید

در اینجا یک مثال است:

GET https://www.googleapis.com/books/v1/users/1112223334445556677/bookshelves/3/volumes?key=yourAPIKey

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

از آنجایی که کاربر برای بازیابی اطلاعات مربوط به قفسه های عمومی نیازی به احراز هویت نیست، لازم نیست سرصفحه HTTP Authorization با درخواست GET ارائه دهید.

پاسخ

اگر درخواست موفق شد، سرور با یک کد وضعیت HTTP 200 OK و لیست قفسه‌های کتاب کاربر پاسخ می‌دهد:

200 OK

{
 "kind": "books#volumes",
 "items": [
  {
   "kind": "books#volume",
   "id": "AZ5J6B1-4BoC",
   "etag": "kIzQA7IUObk",
   "selfLink": "https://www.googleapis.com/books/v1/volumes/AZ5J6B1-4BoC",
   "volumeInfo": {
    "title": "The Girl Who Kicked the Hornet's Nest",
    "authors": [
     "Stieg Larsson"
    ],
    "publisher": "Knopf",
    "publishedDate": "2010-05-25",
    ...
  },
  {
   "kind": "books#volume",
   "id": "UvK1Slvkz3MC",
   "etag": "otKmdbRgdFQ",
   "selfLink": "https://www.googleapis.com/books/v1/volumes/UvK1Slvkz3MC",
   "volumeInfo": {
    "title": "The Girl who Played with Fire",
    "authors": [
     "Stieg Larsson"
    ],
    "publisher": "Knopf",
    "publishedDate": "2009-07-28",
    ...
  },
  {
   "kind": "books#volume",
   "id": "OBM3AAAAIAAJ",
   "etag": "xb47kTr8HsQ",
   "selfLink": "https://www.googleapis.com/books/v1/volumes/OBM3AAAAIAAJ",
   "volumeInfo": {
    "title": "The Sign of Four",
    "authors": [
     "Sir Arthur Conan Doyle"
    ],
    "publishedDate": "1890",
    ...
  }
 ],
 "totalItems": 3
}

پارامترهای پرس و جو اختیاری

علاوه بر پارامترهای پرس و جوی استاندارد ، هنگام بازیابی فهرستی از جلدها در یک قفسه کتاب عمومی، می توانید از پارامتر پرس و جو زیر استفاده کنید.

صفحه بندی

می توانید با تعیین دو مقدار در پارامترهای درخواست، فهرست حجم ها را صفحه بندی کنید:

  • startIndex - موقعیتی در مجموعه که از آن شروع می شود. شاخص مورد اول 0 است.
  • maxResults - حداکثر تعداد نتایج برای بازگشت. پیش فرض 10 و حداکثر مقدار مجاز 40 است.

کار با قفسه کتاب در "کتابخانه من"

تمام درخواست‌های «کتابخانه من» برای داده‌های کاربر تأیید شده اعمال می‌شود.

در حال بازیابی فهرستی از قفسه های کتابم

با ارسال یک درخواست HTTP GET به URI با فرمت زیر می‌توانید فهرستی از تمام قفسه‌های کتاب کاربر تأیید شده را بازیابی کنید:

https://www.googleapis.com/books/v1/mylibrary/bookshelves

درخواست کنید

در اینجا یک مثال است:

GET https://www.googleapis.com/books/v1/mylibrary/bookshelves?key=yourAPIKey
Authorization: /* auth token here */

توجه: کاربر باید برای بازیابی فهرستی از قفسه‌های کتاب «کتابخانه من» احراز هویت شود. بنابراین شما باید هدر HTTP Authorization را با درخواست GET ارائه دهید.

پاسخ

اگر درخواست با موفقیت انجام شود، سرور با کد وضعیت HTTP 200 OK و لیست تمام قفسه‌های کتاب برای کاربر تأیید شده فعلی پاسخ می‌دهد:

200 OK

{
 "kind": "books#bookshelves",
 "items": [
  {
   "kind": "books#bookshelf",
   "id": 0,
   "selfLink": "https://www.googleapis.com/books/v1/users/1112223334445556677/bookshelves/0",
   "title": "Favorites",
   "access": "PRIVATE",
   "updated": "2011-04-22T04:03:15.416Z",
   "created": "2011-04-22T04:03:15.416Z",
   "volumeCount": 0,
   "volumesLastUpdated": "2011-04-22T04:03:17.000Z"
  },
  {
   "kind": "books#bookshelf",
   "id": 3,
   "selfLink": "https://www.googleapis.com/books/v1/users/1112223334445556677/bookshelves/3",
   "title": "Reading now",
   "access": "PUBLIC",
   "updated": "2010-11-11T19:44:22.377Z",
   "created": "2010-11-11T19:44:22.377Z",
   "volumeCount": 1,
   "volumesLastUpdated": "2010-11-11T19:44:22.341Z"
  }
 ]
}

پارامترهای پرس و جو اختیاری

هنگام بازیابی لیست قفسه های کتاب کاربر تأیید شده می توانید از پارامترهای پرس و جو استاندارد استفاده کنید.

در حال بازیابی فهرستی از مجلدات در قفسه کتاب من

با ارسال یک درخواست HTTP GET به URI با فرمت زیر می‌توانید فهرستی از مجلدات موجود در قفسه کتاب کاربر تأیید شده را بازیابی کنید:

https://www.googleapis.com/books/v1/mylibrary/bookshelves/shelf/volumes

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

درخواست کنید

در اینجا یک مثال است:

GET https://www.googleapis.com/books/v1/mylibrary/bookshelves/7/volumes?key=yourAPIKey
Authorization: /* auth token here */

توجه: کاربر باید برای بازیابی فهرستی از جلدهای "کتابخانه من" احراز هویت شود. بنابراین شما باید هدر HTTP Authorization را با درخواست GET ارائه دهید.

پاسخ

اگر درخواست با موفقیت انجام شود، سرور با کد وضعیت HTTP 200 OK و فهرست جلدهای قفسه کتاب پاسخ می دهد:

200 OK

{
 "kind": "books#volumes",
 "items": [
  {
   "kind": "books#volume",
   "id": "AZ5J6B1-4BoC",
   "etag": "kIzQA7IUObk",
   "selfLink": "https://www.googleapis.com/books/v1/volumes/AZ5J6B1-4BoC",
   "volumeInfo": {
    "title": "The Girl Who Kicked the Hornet's Nest",
    "authors": [
     "Stieg Larsson"
    ],
    "publisher": "Knopf",
    "publishedDate": "2010-05-25",
    ...
  },
  {
   "kind": "books#volume",
   "id": "UvK1Slvkz3MC",
   "etag": "otKmdbRgdFQ",
   "selfLink": "https://www.googleapis.com/books/v1/volumes/UvK1Slvkz3MC",
   "volumeInfo": {
    "title": "The Girl who Played with Fire",
    "authors": [
     "Stieg Larsson"
    ],
    "publisher": "Knopf",
    "publishedDate": "2009-07-28",
    ...
  },
  {
   "kind": "books#volume",
   "id": "OBM3AAAAIAAJ",
   "etag": "xb47kTr8HsQ",
   "selfLink": "https://www.googleapis.com/books/v1/volumes/OBM3AAAAIAAJ",
   "volumeInfo": {
    "title": "The Sign of Four",
    "authors": [
     "Sir Arthur Conan Doyle"
    ],
    "publishedDate": "1890",
    ...
  }
 ],
 "totalItems": 3
}

پارامترهای پرس و جو اختیاری

علاوه بر پارامترهای پرس و جوی استاندارد ، هنگام بازیابی فهرستی از جلدها در یکی از قفسه های کتاب کاربر تأیید شده، می توانید از پارامتر پرس و جو زیر استفاده کنید.

صفحه بندی

می توانید با تعیین دو مقدار در پارامترهای درخواست، فهرست حجم ها را صفحه بندی کنید:

  • startIndex - موقعیتی در مجموعه که از آن شروع می شود. شاخص مورد اول 0 است.
  • maxResults - حداکثر تعداد نتایج برای بازگشت. پیش فرض 10 است.

اضافه کردن یک جلد به قفسه کتاب من

برای افزودن یک جلد به قفسه کتاب کاربر تأیید شده، یک درخواست HTTP POST با فرمت زیر به URI ارسال کنید:

https://www.googleapis.com/books/v1/mylibrary/bookshelves/shelf/addVolume

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

درخواست دارای یک پارامتر پرس و جو مورد نیاز است:

درخواست کنید

در اینجا مثالی برای افزودن «گل‌ها برای الجرنون» به قفسه کتاب «مورد علاقه» آورده شده است:

POST https://www.googleapis.com/books/v1/mylibrary/bookshelves/0/addVolume?volumeId=NRWlitmahXkC&key=yourAPIKey
Authorization: /* auth token here */
Content-Type: application/json
Content-Length: CONTENT_LENGTH

توجه: کاربر باید برای ایجاد تغییرات در قفسه کتاب احراز هویت شود، بنابراین باید سرصفحه HTTP Authorization با درخواست POST ارائه دهید. با این حال، هیچ داده ای با این POST مورد نیاز نیست.

پاسخ

اگر درخواست با موفقیت انجام شود، سرور با کد وضعیت HTTP 204 No Content پاسخ می دهد.

پارامترهای پرس و جو اختیاری

هنگام افزودن یک جلد به یکی از قفسه های کتاب کاربر تأیید شده، می توانید از پارامترهای پرس و جو استاندارد استفاده کنید.

در حال برداشتن یک جلد از قفسه کتابم

برای حذف یک جلد از قفسه کتاب کاربر تأیید شده، یک HTTP POST با فرمت زیر به URI ارسال کنید:

https://www.googleapis.com/books/v1/mylibrary/bookshelves/shelf/removeVolume

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

درخواست دارای یک پارامتر پرس و جو مورد نیاز است:

درخواست کنید

در اینجا مثالی برای حذف «گل‌ها برای الجرنون» از قفسه کتاب «مورد علاقه» آورده شده است:

POST https://www.googleapis.com/books/v1/mylibrary/bookshelves/0/removeVolume?volumeId=NRWlitmahXkC&key=yourAPIKey
Authorization: /* auth token here */
Content-Type: application/json
Content-Length: CONTENT_LENGTH

توجه: کاربر باید برای ایجاد تغییرات در قفسه کتاب احراز هویت شود، بنابراین باید سرصفحه HTTP Authorization با درخواست POST ارائه دهید. با این حال، هیچ داده ای با این POST مورد نیاز نیست.

پاسخ

اگر درخواست با موفقیت انجام شود، سرور با یک کد وضعیت 204 No Content پاسخ می دهد.

پارامترهای پرس و جو اختیاری

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

پاک کردن تمام جلدها از قفسه کتابم

برای حذف تمام جلدها از قفسه کتاب کاربر تأیید شده، یک HTTP POST با فرمت زیر به URI ارسال کنید:

https://www.googleapis.com/books/v1/mylibrary/bookshelves/shelf/clearVolumes

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

درخواست کنید

در اینجا یک مثال برای پاک کردن قفسه کتاب "مورد علاقه" آورده شده است:

POST https://www.googleapis.com/books/v1/mylibrary/bookshelves/0/clearVolumes?key=yourAPIKey
Authorization: /* auth token here */
Content-Type: application/json
Content-Length: CONTENT_LENGTH
  

توجه: کاربر باید برای ایجاد تغییرات در قفسه کتاب احراز هویت شود، بنابراین باید سرصفحه HTTP Authorization با درخواست POST ارائه دهید. با این حال، هیچ داده ای با این POST مورد نیاز نیست.

پاسخ

اگر درخواست با موفقیت انجام شود، سرور با یک کد وضعیت 204 No Content پاسخ می دهد.

پارامترهای پرس و جو اختیاری

هنگام پاک کردن تمام جلدها از یکی از قفسه های کتاب احراز هویت شده، می توانید از پارامترهای پرس و جوی استاندارد استفاده کنید.

مرجع پارامتر پرس و جو

پارامترهای پرس و جو که می توانید با Books API استفاده کنید در این بخش خلاصه شده است. همه مقادیر پارامتر باید URL کدگذاری شوند.

پارامترهای پرس و جو استاندارد

پارامترهای پرس و جو که برای همه عملیات Books API اعمال می شوند در System Parameters مستند می شوند.

پارامترهای پرس و جو مخصوص API

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

پارامتر معنی یادداشت ها قابلیت کاربرد
download با در دسترس بودن دانلود به حجم محدود کنید.
  • در حال حاضر، تنها مقدار پشتیبانی شده epub است.
  • ممکن است برای دسترسی به دانلود نیاز به خرید باشد.
filter نتایج جستجو را بر اساس نوع حجم و در دسترس بودن فیلتر کنید.
  • فیلترهای پشتیبانی شده عبارتند از:
    • filter=partial - نتایج را به حجم هایی که حداقل بخشی از متن قابل پیش نمایش است محدود کنید.
    • filter=full - نتایج را به حجم هایی که تمام متن قابل مشاهده است محدود کنید.
    • filter=free-ebooks - نتایج را به کتاب‌های الکترونیکی رایگان Google محدود کنید.
    • filter=paid-ebooks - نتایج را با قیمت خرید به Google eBooks محدود کنید.
    • filter=ebooks - نتایج را به کتاب‌های الکترونیکی Google، پولی یا رایگان محدود کنید. نمونه‌هایی از کتاب‌های غیر الکترونیکی محتوای ناشر است که در پیش‌نمایش محدود و برای فروش در دسترس نیست، یا مجلات.

langRestrict مجلدات بازگردانده شده را محدود به آنهایی می کند که با زبان مشخص شده برچسب گذاری شده اند.
  • با مشخص کردن langRestrict به کد ISO-639-1 دو حرفی، مانند "en" یا "fr"، نتایج جستجو را به کسانی که زبان خاصی دارند محدود کنید.
maxResults حداکثر تعداد عناصر برای بازگشت با این درخواست.
  • برای هر درخواستی برای همه موارد در یک مجموعه، می‌توانید نتایج را با تعیین startIndex و maxResults در پارامترهای درخواست صفحه‌بندی کنید.
  • پیش فرض: maxResults=10
  • حداکثر مقدار مجاز: maxResults=40.
orderBy

ترتیب نتایج جستجوی حجمی

  • به‌طور پیش‌فرض، یک درخواست جستجو نتایج maxResults را برمی‌گرداند، که در آن maxResults پارامتری است که در صفحه‌بندی استفاده می‌شود، که ابتدا توسط اکثر مرتبط‌ها مرتب می‌شود.
  • با تنظیم پارامتر orderBy به عنوان یکی از این مقادیر می توانید ترتیب را تغییر دهید:
    • orderBy=relevance - نتایج جستجو را به ترتیب مرتبط ترین به حداقل برمی گرداند (این پیش فرض است).
    • orderBy=newest - نتایج جستجو را به ترتیب جدیدترین تاریخ منتشر شده به قدیمی ترین برمی گرداند.
printType محدود به کتاب یا مجلات.
  • مقادیر پشتیبانی شده عبارتند از:
    • printType=all - همه انواع محتوای حجمی را برگردانید (بدون محدودیت). این پیش فرض است.
    • printType=books - فقط کتابها را برگردانید.
    • printType=magazines - فقط مجلات را برگردانید.
projection محدود کردن اطلاعات حجم بازگردانده شده به زیر مجموعه ای از فیلدها.
  • پیش بینی های پشتیبانی شده عبارتند از:
    • projection=full - شامل تمام ابرداده های حجم (پیش فرض).
    • projection=lite - فقط شامل یک موضوع حجم و فراداده دسترسی است.
q رشته پرس و جو تمام متن.
  • هنگام ایجاد یک پرس و جو، عبارات جستجو را به شکل q =term1+term2_term3 جدا کنید که با یک "+" از هم جدا شده اند. (به طور متناوب، می توانید آنها را با یک فاصله از هم جدا کنید، اما مانند همه مقادیر پارامتر پرس و جو، فضاها باید سپس URL کدگذاری شوند.) API همه ورودی هایی را که با همه عبارات جستجو مطابقت دارند (مانند استفاده از AND بین عبارت ها) برمی گرداند. مانند جستجوی وب گوگل، API کلمات کامل (و کلمات مرتبط با همان ریشه) را جستجو می کند، نه رشته های فرعی.
  • برای جستجوی یک عبارت دقیق، عبارت را در گیومه قرار دهید: q="exact phrase" .
  • برای حذف ورودی‌هایی که با یک عبارت مشخص مطابقت دارند، از فرم q=-term استفاده کنید.
  • عبارات جستجو به حروف بزرگ و کوچک حساس هستند.
  • مثال: برای جستجوی تمام ورودی‌هایی که حاوی عبارت دقیق "Elizabeth Bennet" و کلمه "Darcy" هستند اما حاوی کلمه "Austen" نیستند، از مقدار پارامتر پرس و جو زیر استفاده کنید:
    q="Elizabeth+Bennet"+Darcy-Austen
  • کلمات کلیدی خاصی (حساس به حروف کوچک و بزرگ) وجود دارد که می توانید در عبارات جستجو برای جستجو در فیلدهای خاص مشخص کنید، مانند:
    • intitle : نتایجی را برمی‌گرداند که متن زیر این کلمه کلیدی در عنوان یافت می‌شود.
    • inauthor : نتایجی را برمی‌گرداند که متن زیر این کلمه کلیدی در نویسنده یافت می‌شود.
    • inpublisher : نتایجی را برمی‌گرداند که متن زیر این کلمه کلیدی در ناشر پیدا می‌شود.
    • subject : نتایجی را برمی‌گرداند که متن زیر این کلمه کلیدی در فهرست دسته‌بندی جلد فهرست شده است.
    • isbn : نتایجی را برمی‌گرداند که متن زیر این کلمه کلیدی شماره ISBN باشد.
    • lccn : نتایجی را برمی‌گرداند که متن زیر این کلمه کلیدی شماره کنترل کتابخانه کنگره باشد.
    • oclc : نتایجی را برمی‌گرداند که متن زیر این کلمه کلیدی شماره مرکز کتابخانه رایانه آنلاین باشد.
startIndex موقعیتی در مجموعه که در آن لیست نتایج شروع می شود.
  • برای هر درخواستی برای همه موارد در یک مجموعه، می‌توانید نتایج را با تعیین startIndex و maxResults در پارامترهای درخواست صفحه‌بندی کنید.
  • شاخص مورد اول 0 است.
volumeId حجم مرتبط با درخواست را مشخص می کند.
  • حجم برای افزودن یا حذف از قفسه کتاب را مشخص می کند.