เริ่มต้นใช้งาน

เอกสารนี้จะอธิบายความรู้พื้นฐานที่คุณต้องมีเพื่อใช้ Google Books API

บทนำ
ก่อนเริ่มต้น
ข้อมูลพื้นฐานเกี่ยวกับ Books API
รูปแบบการโทร
1. REST
รูปแบบข้อมูล
1. JSON

บทนำ

เอกสารนี้มีไว้สำหรับนักพัฒนาซอฟต์แวร์ที่ต้องการเขียนแอปพลิเคชันที่ โต้ตอบกับ Google Books API ได้ Google Books มีวิสัยทัศน์ที่จะแปลงหนังสือทั่วโลกให้เป็นดิจิทัล คุณใช้ Google Books API เพื่อ ค้นหาเนื้อหา จัดระเบียบคลังส่วนตัวของผู้ใช้ที่ได้รับการตรวจสอบสิทธิ์ และแก้ไขคลังนั้น ได้ด้วย

ก่อนจะเริ่มต้น

สร้างบัญชี Google

คุณต้องมีบัญชี Google เพื่อวัตถุประสงค์ในการทดสอบ หากมีบัญชีทดสอบอยู่แล้ว คุณก็พร้อมใช้งาน โดยสามารถไปที่อินเทอร์เฟซผู้ใช้ Google Books เพื่อตั้งค่า แก้ไข หรือดูข้อมูลทดสอบได้

ทำความคุ้นเคยกับ Books

หากยังไม่คุ้นเคยกับแนวคิดของ Google Books คุณควรอ่านเอกสารนี้และทดลองใช้อินเทอร์เฟซผู้ใช้ ก่อนเริ่มเขียนโค้ด เอกสารนี้ถือว่าคุณคุ้นเคยกับแนวคิดการเขียนโปรแกรมบนเว็บและรูปแบบข้อมูลเว็บ

ดูข้อมูลเกี่ยวกับการให้สิทธิ์คำขอและการระบุแอปพลิเคชันของคุณ

เมื่อแอปพลิเคชันขอข้อมูลส่วนตัว คำขอจะต้องได้รับสิทธิ์จากผู้ใช้ที่ตรวจสอบสิทธิ์แล้วซึ่งมีสิทธิ์เข้าถึงข้อมูลดังกล่าว

โดยเฉพาะอย่างยิ่ง การดำเนินการทั้งหมดในส่วน "คลังของฉัน" ใน Google Books API ถือเป็นการดำเนินการแบบส่วนตัวและต้องมีการตรวจสอบสิทธิ์และการให้สิทธิ์ นอกจากนี้ ผู้ใช้ที่เป็นเจ้าของข้อมูล Google Books เท่านั้นที่จะดำเนินการใดๆ ที่แก้ไขข้อมูลดังกล่าวได้

เมื่อแอปพลิเคชันขอข้อมูลสาธารณะ คำขอไม่จำเป็นต้องได้รับสิทธิ์ แต่ต้องมีตัวระบุ เช่น คีย์ API

ดูข้อมูลเกี่ยวกับวิธีให้สิทธิ์คำขอและใช้คีย์ API ได้ที่การให้สิทธิ์คำขอและการระบุแอปพลิเคชันของคุณในเอกสารการใช้ API

พื้นฐานเกี่ยวกับ Books API

แนวคิดเกี่ยวกับหนังสือ

Google Books สร้างขึ้นจากแนวคิดพื้นฐาน 4 ประการดังนี้

เล่ม: เล่มแสดงถึงข้อมูลที่ Google Books โฮสต์เกี่ยวกับ หนังสือหรือนิตยสาร ซึ่งเป็นทรัพยากรหลักใน Books API ทรัพยากรอื่นๆ ทั้งหมด ใน API นี้มีหรืออธิบายประกอบเกี่ยวกับวอลุ่ม
ชั้นวางหนังสือ: ชั้นวางหนังสือคือคอลเล็กชันของหนังสือ Google Books มีชั้นหนังสือที่กำหนดไว้ล่วงหน้าสำหรับผู้ใช้แต่ละราย โดยผู้ใช้จะจัดการชั้นหนังสือบางชั้นได้โดยสมบูรณ์ ระบบจะป้อนข้อมูลในชั้นหนังสือบางชั้นโดยอัตโนมัติ ตามกิจกรรมของผู้ใช้ และชั้นหนังสือบางชั้นก็จะเป็นแบบผสม ผู้ใช้สามารถสร้าง แก้ไข หรือลบชั้นวางหนังสืออื่นๆ ซึ่งจะเต็มไปด้วยหนังสือ ที่เพิ่มด้วยตนเองเสมอ ผู้ใช้สามารถตั้งค่าชั้นวางหนังสือให้เป็นแบบส่วนตัวหรือสาธารณะได้
หมายเหตุ: ปัจจุบันคุณสร้างและลบชั้นวางหนังสือ รวมถึงแก้ไขการตั้งค่าความเป็นส่วนตัวในชั้นวางหนังสือได้ผ่านเว็บไซต์ Google Books เท่านั้น
รีวิว: รีวิวของหนังสือเป็นการผสมผสานระหว่างการให้คะแนนเป็นดาว และ/หรือข้อความ ผู้ใช้จะส่งรีวิวได้ 1 รายการต่อเล่ม นอกจากนี้ รีวิวยังมาจากแหล่งที่มาภายนอกและมีการระบุแหล่งที่มาอย่างเหมาะสมด้วย
ตำแหน่งการอ่าน: ตำแหน่งการอ่านจะระบุตำแหน่งที่อ่านล่าสุดในเล่มสำหรับผู้ใช้ ผู้ใช้จะมีตำแหน่งการอ่านได้เพียงตำแหน่งเดียวต่อ หนังสือ หากผู้ใช้ยังไม่เคยเปิดเล่มนั้นมาก่อน ก็จะไม่มีตำแหน่งการอ่าน ตำแหน่งการอ่านสามารถจัดเก็บข้อมูลตำแหน่งโดยละเอียดได้จนถึงระดับความละเอียดของคำ ข้อมูลนี้จะเป็นข้อมูลส่วนตัวของผู้ใช้เสมอ

รูปแบบข้อมูล Books API

ทรัพยากรคือเอนทิตีข้อมูลแต่ละรายการที่มีตัวระบุที่ไม่ซ้ำกัน Books API ทำงานกับทรัพยากร 2 ประเภทตามแนวคิดที่อธิบายไว้ ข้างต้น

ทรัพยากรระดับเสียง: แสดงถึงระดับเสียง
แหล่งข้อมูลชั้นหนังสือ: แสดงถึงชั้นหนังสือเดียวสำหรับผู้ใช้ รายใดรายหนึ่ง

โมเดลข้อมูลของ Books API อิงตามกลุ่มของทรัพยากรที่เรียกว่าคอลเล็กชัน

การรวบรวมข้อมูลปริมาณการใช้งาน: คอลเล็กชันเล่มคือคอลเล็กชัน ของทรัพยากรเล่มทั้งหมดที่ Google Books จัดการ ดังนั้น คุณจึงแสดงทรัพยากรระดับปริมาณทั้งหมดไม่ได้ แต่คุณแสดงโวลุ่มทั้งหมดที่ตรงกับชุด ข้อความค้นหาได้
คอลเล็กชันชั้นวางหนังสือ: คอลเล็กชันชั้นวางหนังสือประกอบด้วยแหล่งข้อมูลชั้นวางหนังสือทั้งหมดที่ Google Books จัดการ ชั้นวางหนังสือต้องอ้างอิงในบริบทของคลังของผู้ใช้ที่เฉพาะเจาะจงเสมอ ชั้นวางหนังสืออาจมีหนังสือ 0 เล่มขึ้นไป

การดำเนินการของ Books API

คุณเรียกใช้เมธอดต่างๆ 5 วิธีในคอลเล็กชันและทรัพยากรใน Books API ได้ตามที่อธิบายไว้ในตารางต่อไปนี้

การดำเนินการ	คำอธิบาย	การแมป HTTP ของ REST
list	แสดงรายการชุดย่อยของทรัพยากรที่ระบุภายในคอลเล็กชัน	`GET` ใน URI ของคอลเล็กชัน
แทรก	แทรกทรัพยากรใหม่ลงในคอลเล็กชัน (สร้างทรัพยากรใหม่)	`POST` ใน URI ของคอลเล็กชัน ซึ่งคุณส่งข้อมูลสำหรับทรัพยากรใหม่
รับ	รับทรัพยากรที่เฉพาะเจาะจง	`GET` ใน URI ทรัพยากร
อัปเดต	อัปเดตทรัพยากรที่เฉพาะเจาะจง	`PUT` ใน URI ของทรัพยากร ซึ่งคุณจะส่งข้อมูลสำหรับทรัพยากรที่อัปเดต
ลบ	ลบทรัพยากรที่เฉพาะเจาะจง	`DELETE` ใน URI ของทรัพยากร ซึ่งคุณจะส่งข้อมูลสำหรับทรัพยากรที่จะลบ

การดำเนินการที่รองรับสำหรับทรัพยากรประเภทต่างๆ จะสรุปไว้ในตารางด้านล่าง การดำเนินการที่ใช้กับข้อมูลส่วนตัวของผู้ใช้เรียกว่าการดำเนินการ "คลังของฉัน" และการดำเนินการทั้งหมดต้องใช้การตรวจสอบสิทธิ์

ประเภททรัพยากร	การดำเนินการที่รองรับ
	list	แทรก	get	อัปเดต	ลบ
ระดับเสียง	ใช่*		ใช่
ชั้นวางหนังสือ	ใช่*	ใช่ AUTHENTICATED	ใช่*	ใช่ AUTHENTICATED	ใช่ AUTHENTICATED
ตำแหน่งการอ่าน		ใช่ AUTHENTICATED	ใช่ AUTHENTICATED	ใช่ AUTHENTICATED	ใช่ AUTHENTICATED

*ทั้งเวอร์ชันที่ตรวจสอบสิทธิ์แล้วและเวอร์ชันที่ไม่ได้ตรวจสอบสิทธิ์ของโอเปอเรชันเหล่านี้พร้อมใช้งาน โดยคำขอที่ตรวจสอบสิทธิ์แล้วจะดำเนินการกับข้อมูล "คลังของฉัน" ส่วนตัวของผู้ใช้ และคำขอที่ไม่ได้ตรวจสอบสิทธิ์จะดำเนินการกับข้อมูลสาธารณะเท่านั้น

รูปแบบการโทร

คุณเรียกใช้ API ได้หลายวิธี ดังนี้

การใช้ REST โดยตรง
การใช้ REST จาก JavaScript (ไม่จำเป็นต้องมีโค้ดฝั่งเซิร์ฟเวอร์)

REST

REST เป็นรูปแบบสถาปัตยกรรมซอฟต์แวร์ที่ให้แนวทางที่สะดวกและสอดคล้องกันในการขอและแก้ไขข้อมูล

คำว่า REST ย่อมาจาก "Representational State Transfer" ในบริบทของ Google API คำนี้หมายถึงการใช้คำกริยา HTTP เพื่อดึงและแก้ไขการแสดงข้อมูลที่ Google จัดเก็บไว้

ในระบบ RESTful ระบบจะจัดเก็บทรัพยากรในที่เก็บข้อมูล ไคลเอ็นต์จะส่งคำขอให้เซิร์ฟเวอร์ดำเนินการใดดำเนินการหนึ่ง (เช่น สร้าง เรียกข้อมูล อัปเดต หรือลบทรัพยากร) และเซิร์ฟเวอร์จะดำเนินการและส่งการตอบกลับ ซึ่งมักจะอยู่ในรูปแบบของการแสดงทรัพยากรที่ระบุ

ใน RESTful API ของ 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 คือ พารามิเตอร์ที่จะใช้กับคำค้นหา ดูรายละเอียดได้ที่ข้อมูลอ้างอิงพารามิเตอร์การค้นหา

รูปแบบของ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

ต่อไปนี้เป็นตัวอย่าง 2 รายการที่แสดงวิธีการทำงานนี้ใน Books API

ค้นหาการเย็บผ้า

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

รับข้อมูลเกี่ยวกับเล่ม s1gVAAAAYAAJ

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

REST จาก JavaScript

คุณสามารถเรียกใช้ Books API โดยใช้ REST จาก JavaScript (หรือที่เรียกว่า JSON-P) โดยใช้พารามิเตอร์การค้นหา callback และฟังก์ชันเรียกกลับ ซึ่งจะช่วยให้คุณเขียนแอปพลิเคชันที่ครบวงจรซึ่งแสดงข้อมูลหนังสือได้โดยไม่ต้องเขียนโค้ดฝั่งเซิร์ฟเวอร์

หมายเหตุ: คุณเรียกใช้เมธอดที่ตรวจสอบสิทธิ์แล้วได้โดยส่งโทเค็น OAuth 2.0 โดยใช้พารามิเตอร์ access_token หากต้องการรับโทเค็น OAuth 2.0 เพื่อใช้กับ JavaScript ให้ทำตามวิธีการที่อธิบายไว้ใน OAuth 2.0 สำหรับเว็บแอปพลิเคชันฝั่งไคลเอ็นต์ ในแท็บ "การเข้าถึง API" ของ API Console ให้ตั้งค่ารหัสไคลเอ็นต์สำหรับเว็บแอปพลิเคชัน และใช้ข้อมูลเข้าสู่ระบบ 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