شروع شدن (original) (raw)
این سند اطلاعات پیشزمینهای را که برای استفاده از Google Books API نیاز دارید، توضیح میدهد.
مقدمه
این سند برای توسعه دهندگانی است که می خواهند برنامه هایی بنویسند که بتوانند با 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 توضیح داده شده است.
فرمت خاص برای Books API URI عبارتند از:
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 هنگام دریافت توکن خود استفاده کنید.
مثال زیر از این روش برای نمایش نتایج جستجو برای "هری پاتر" استفاده می کند:
Books API Exampleفرمت داده
JSON
JSON (JavaScript Object Notation) یک قالب داده رایج و مستقل از زبان است که نمایش متنی ساده ای از ساختارهای داده دلخواه را ارائه می دهد. برای اطلاعات بیشتر، به json.org مراجعه کنید.