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

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

1. บทนำ
2. ก่อนเริ่มต้น
   1. สร้างบัญชี Google
   2. ทำความคุ้นเคยกับ Books
   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 หนังสือ เพื่อตั้งค่า แก้ไข หรือดูข้อมูลการทดสอบได้

ทำความคุ้นเคยกับหนังสือ

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

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

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

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

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

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

พื้นหลัง Books API

แนวคิดสำหรับหนังสือ

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

• "รายการโปรด"
• "แฮร์รี่ พอตเตอร์"
• "eBooks ของฉัน"
• "เปลี่ยน"
• "พลบค่ำ"
• "The Girl with the Dragon Tattoo"

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

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

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

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

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

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

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

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

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

REST

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

คำว่า REST เป็นคำสั้นๆ ของ "Assignational State 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

การดำเนินการของ 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

ตัวอย่างวิธีการทำงานใน 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 และฟังก์ชัน Callback ซึ่งจะช่วยให้คุณเขียนแอปพลิเคชันที่มีการจัดรูปแบบซึ่งแสดงข้อมูล Books ได้โดยไม่ต้องเขียนโค้ดฝั่งเซิร์ฟเวอร์ใดๆ

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