شروع شدن

این سند اطلاعات پیش‌زمینه‌ای را که برای استفاده از Google Books API نیاز دارید، توضیح می‌دهد.

1. مقدمه
2. قبل از اینکه تو شروع کنی
   1. یک حساب Google دریافت کنید
   2. با کتاب ها آشنا شوید
   3. درباره مجوز دادن به درخواست ها و شناسایی برنامه خود بیاموزید
3. پس‌زمینه Books API
   1. مفاهیم کتاب
   2. مدل داده Books API
   3. عملیات Books API
4. سبک تماس
   1. باقی مانده
5. فرمت داده
   1. JSON

مقدمه

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

قبل از اینکه تو شروع کنی

یک حساب Google دریافت کنید

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

با کتاب ها آشنا شوید

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

درباره مجوز دادن به درخواست ها و شناسایی برنامه خود بیاموزید

هنگامی که برنامه شما داده های خصوصی را درخواست می کند، درخواست باید توسط یک کاربر احراز هویت که به آن داده ها دسترسی دارد مجاز باشد.

به ویژه، همه عملیات تحت «کتابخانه من» در Google Books API خصوصی در نظر گرفته می‌شوند و نیاز به احراز هویت و مجوز دارند. علاوه بر این، هر عملیاتی که داده‌های Google Books را تغییر می‌دهد، تنها توسط کاربری که آن داده‌ها را در اختیار دارد، می‌تواند انجام شود.

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

برای اطلاعات در مورد نحوه مجوز دادن به درخواست‌ها و استفاده از کلیدهای API، به تأیید درخواست‌ها و شناسایی برنامه‌تان در سند استفاده از API مراجعه کنید.

پس‌زمینه Books API

مفاهیم کتاب

Google Books بر اساس چهار مفهوم اساسی ساخته شده است:

• جلد : یک جلد نشان دهنده داده هایی است که Google Books درباره یک کتاب یا مجله میزبانی می کند. این منبع اصلی در Books API است. همه منابع دیگر در این API یا حاوی یک جلد هستند یا حاشیه نویسی می کنند.
• قفسه کتاب : قفسه کتاب مجموعه ای از مجلدات است. Google Books مجموعه ای از قفسه های کتاب از پیش تعریف شده را برای هر کاربر ارائه می دهد که برخی از آنها به طور کامل توسط کاربر مدیریت می شوند، برخی از آنها به طور خودکار بر اساس فعالیت کاربر پر می شوند و برخی از آنها ترکیبی هستند. کاربران می‌توانند قفسه‌های کتاب دیگری را ایجاد، اصلاح یا حذف کنند، که همیشه با جلدها به صورت دستی پر می‌شوند. قفسه های کتاب می تواند توسط کاربر خصوصی یا عمومی شود.

  توجه: ایجاد و حذف قفسه‌های کتاب و همچنین تغییر تنظیمات حریم خصوصی در قفسه‌ها در حال حاضر فقط از طریق سایت Google Books امکان‌پذیر است.

• بررسی : بررسی یک جلد، ترکیبی از رتبه بندی ستاره و/یا متن است. یک کاربر می تواند یک نظر در هر جلد ارسال کند. بررسی ها نیز از منابع خارجی در دسترس هستند و به طور مناسب نسبت داده می شوند.
• موقعیت خواندن : موقعیت خواندن آخرین موقعیت خواندن در یک حجم را برای کاربر نشان می دهد. یک کاربر فقط می تواند یک موقعیت خواندن در هر جلد داشته باشد. اگر کاربر قبلاً آن حجم را باز نکرده باشد، موقعیت خواندن وجود ندارد. موقعیت خواندن می تواند اطلاعات موقعیت دقیق را تا وضوح یک کلمه ذخیره کند. این اطلاعات همیشه برای کاربر خصوصی است.

مدل داده Books API

یک منبع یک موجودیت داده منفرد با یک شناسه منحصر به فرد است. Books API بر اساس مفاهیمی که در بالا توضیح داده شد بر روی دو نوع منبع عمل می کند:

• منبع حجم : یک حجم را نشان می دهد.
• منبع قفسه کتاب : نشان دهنده یک قفسه کتاب برای یک کاربر خاص است.

مدل داده‌های Books API بر اساس گروه‌هایی از منابع است که مجموعه‌ها نامیده می‌شوند:

مجموعه حجم

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

مجموعه قفسه کتاب

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

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

• موارد مورد علاقه: قفسه کتاب قابل تغییر.
• خریداری شده: دارای حجم هایی است که کاربر خریداری کرده است. کاربر نمی تواند به صورت دستی حجم ها را اضافه یا حذف کند.
• خواندن: قفسه کتاب قابل تغییر.
• اکنون در حال خواندن: قفسه کتاب قابل تغییر.
• خوانده اید: قفسه کتاب قابل تغییر.
• بازبینی شده: پر از جلدهایی است که کاربر بررسی کرده است. کاربر نمی تواند به صورت دستی حجم ها را اضافه یا حذف کند.
• اخیراً مشاهده شده: دارای حجم هایی است که کاربر اخیراً در یک وب خوان باز کرده است. کاربر نمی تواند به صورت دستی حجم اضافه کند.
• کتابهای الکترونیکی من: قفسه کتاب قابل تغییر. کتاب‌های خریداری‌شده به‌طور خودکار اضافه می‌شوند، اما می‌توانند به صورت دستی حذف شوند.
• کتاب‌ها برای شما: پر از توصیه‌های جلد شخصی‌شده. اگر هیچ توصیه ای برای کاربر نداریم، این قفسه کتاب وجود ندارد.

نمونه قفسه کتاب:

• "موارد دلخواه"
• "هری پاتر"
• "کتاب های الکترونیکی من"
• "تعویض"
• "گرگ و میش"
• "دختری با خال کوبی اژدها"

عملیات Books API

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

عمل	شرح	REST نگاشت HTTP
فهرست	زیر مجموعه مشخصی از منابع را در یک مجموعه فهرست می کند.	GET URI مجموعه.
درج کنید	یک منبع جدید را در مجموعه درج می کند (ایجاد یک منبع جدید).	در یک URI مجموعه POST ، جایی که داده ها را برای یک منبع جدید ارسال می کنید.
گرفتن	یک منبع خاص می گیرد.	GET URI منبع.
به روز رسانی	یک منبع خاص را به روز می کند.	URI منبع را PUT ، جایی که داده ها را برای منبع به روز شده ارسال می کنید.
حذف	یک منبع خاص را حذف می کند.	DELETE در URI منبع، جایی که داده‌ها را برای حذف منبع ارسال می‌کنید.

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

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

*هر دو نسخه احراز هویت و احراز هویت نشده از این عملیات در دسترس هستند، که در آن درخواست‌های احراز هویت شده بر روی داده‌های خصوصی کاربر «کتابخانه من» عمل می‌کنند، و درخواست‌های تأیید نشده فقط بر روی داده‌های عمومی عمل می‌کنند.

سبک های فراخوانی

چندین راه برای فراخوانی API وجود دارد:

• استفاده مستقیم از REST
• استفاده از REST از جاوا اسکریپت (بدون نیاز به کد سمت سرور)

باقی مانده

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

اصطلاح REST مخفف " انتقال دولت نمایندگی " است. در زمینه Google API ها، به استفاده از افعال HTTP برای بازیابی و اصلاح نمایش داده های ذخیره شده توسط Google اشاره دارد.

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

در API های RESTful Google، مشتری با استفاده از یک فعل HTTP مانند POST ، GET ، PUT ، یا DELETE اقدامی را مشخص می کند. این یک منبع را توسط یک URI منحصر به فرد جهانی به شکل زیر مشخص می کند:

https://www.googleapis.com/apiName/apiVersion/resourcePath?parameters

از آنجایی که همه منابع API دارای URI های منحصر به فرد قابل دسترسی با HTTP هستند، REST ذخیره داده را فعال می کند و برای کار با زیرساخت های توزیع شده وب بهینه شده است.

ممکن است تعاریف روش را در مستندات استانداردهای HTTP 1.1 مفید بیابید. آنها شامل مشخصات GET ، POST ، PUT و DELETE هستند.

REST در Books API

عملیات Books پشتیبانی شده مستقیماً به افعال HTTP REST نگاشت، همانطور که در عملیات Books API توضیح داده شده است.

فرمت خاص URI های Books API عبارتند از:

https://www.googleapis.com/books/v1/{collectionName}/resourceID?parameters

که در آن resourceID شناسه یک منبع حجم یا قفسه کتاب است و parameters هر پارامتری هستند که باید در پرس و جو اعمال شود. برای جزئیات به مرجع پارامتر Query مراجعه کنید.

فرمت پسوندهای مسیر resourceID به شما امکان می دهد منبعی را که در حال حاضر روی آن کار می کنید شناسایی کنید، به عنوان مثال:

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

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

در اینجا چند نمونه از نحوه عملکرد این در Books API آورده شده است.

جست و جوی لحاف کاری انجام دهید:

GET https://www.googleapis.com/books/v1/volumes?q=quilting

دریافت اطلاعات در مورد حجم s1gVAAAAYAAJ:

GET https://www.googleapis.com/books/v1/volumes/s1gVAAAAYAAJ

REST از جاوا اسکریپت

می‌توانید Books API را با استفاده از REST از جاوا اسکریپت (همچنین JSON-P نامیده می‌شود)، با استفاده از پارامتر callback جوی تماس و یک تابع پاسخ به تماس فراخوانی کنید. این به شما امکان می دهد برنامه های کاربردی غنی بنویسید که داده های Books را بدون نوشتن کد سمت سرور نمایش می دهند.

توجه: می‌توانید روش‌های احراز هویت‌شده را با ارسال یک توکن OAuth 2.0 با استفاده از پارامتر access_token فراخوانی کنید. برای به دست آوردن یک نشانه OAuth 2.0 برای استفاده با جاوا اسکریپت، دستورالعمل های شرح داده شده در OAuth 2.0 برای برنامه های کاربردی وب سمت سرویس گیرنده را دنبال کنید. در برگه «دسترسی به API» در کنسول APIs ، مطمئن شوید که یک Client ID برای برنامه‌های کاربردی وب تنظیم کنید، و از آن اعتبارنامه‌های OAuth 2.0 هنگام دریافت توکن خود استفاده کنید.

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

<html>
  <head>
    <title>Books API Example</title>
  </head>
  <body>
    <div id="content"></div>
    <script>
      function handleResponse(response) {
      for (var i = 0; i < response.items.length; i++) {
        var item = response.items[i];
        // in production code, item.text should have the HTML entities escaped.
        document.getElementById("content").innerHTML += "<br>" + item.volumeInfo.title;
      }
    }
    </script>
    <script src="https://www.googleapis.com/books/v1/volumes?q=harry+potter&callback=handleResponse"></script>
  </body>
</html>

فرمت داده

JSON

JSON (JavaScript Object Notation) یک قالب داده رایج و مستقل از زبان است که نمایش متنی ساده ای از ساختارهای داده دلخواه را ارائه می دهد. برای اطلاعات بیشتر، به json.org مراجعه کنید.