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

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

1. บทนำ
2. ก่อนเริ่มต้น
   1. สร้างบัญชี Google
   2. ทําความคุ้นเคยกับ Books
   3. ดูข้อมูลเกี่ยวกับการให้สิทธิ์คําขอและระบุแอปพลิเคชันของคุณ
3. พื้นหลังใน Books API
   1. แนวคิดเกี่ยวกับหนังสือ
   2. โมเดลข้อมูล Books API
   3. การดําเนินการเกี่ยวกับ Books API
4. รูปแบบการโทร
   1. REST
5. รูปแบบข้อมูล
   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

พื้นหลัง API ของ Books

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

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

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

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

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

โมเดลข้อมูล Books API

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

• ทรัพยากรปริมาณ: แสดงถึงปริมาณ
• แหล่งข้อมูลของชั้นวางหนังสือ: เป็นชั้นวางหนังสือเดียวสําหรับผู้ใช้บางราย

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

การรวบรวมระดับเสียง

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

คอลเล็กชันชั้นวางหนังสือ

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

Google มีชุดชั้นวางหนังสือที่กําหนดไว้ล่วงหน้าสําหรับผู้ใช้แต่ละราย ดังนี้

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

ตัวอย่างชั้นวางหนังสือ

• "รายการโปรด"
• "แฮร์รี่ พอตเตอร์"
• "eBook ของฉัน"
• "เปลี่ยน"
• "แสงสนธยา"
• "รอยสักแห่งมังกรสาว"

API ของ Books

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

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

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

ประเภททรัพยากร	การดําเนินการที่รองรับ
	รายการ	แทรก	รับ	อัปเดต	ลบ
ระดับเสียง	ตั้งค่าได้*		ใช่
ชั้นวางหนังสือ	ตั้งค่าได้*	ใช่ ตรวจสอบสิทธิ์	ตั้งค่าได้*	ใช่ ตรวจสอบสิทธิ์	ใช่ ตรวจสอบสิทธิ์
ตําแหน่งการอ่าน		ใช่ ตรวจสอบสิทธิ์	ใช่ ตรวจสอบสิทธิ์	ใช่ ตรวจสอบสิทธิ์	ใช่ ตรวจสอบสิทธิ์

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

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

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

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

REST

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

คําว่า REST ย่อมาจาก "Agentational Transfer" (การโอนสถานะตัวแทน) ในบริบทของ Google APIs หมายถึงการใช้คํากริยา 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

การดําเนินการเกี่ยวกับหนังสือที่รองรับจะแมปกับคํากริยา 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 จะสรุปไว้ในเอกสารเอกสารอ้างอิงของ API

นี่คือตัวอย่าง 2-3 ข้อของวิธีการทํางานใน Books API

ค้นหาผ้าควิลท์

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

ดูข้อมูลเกี่ยวกับระดับเสียง s1gVAAAAYAAJ:

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

REST จาก JavaScript

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

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