หน้านี้จะอธิบายวิธีใช้บริการที่รองรับโปรโตคอลแหล่งข้อมูลเครื่องมือแผนภูมิเพื่อแสดงข้อมูลในแผนภูมิโดยใช้คลาสการค้นหา
เนื้อหา
ผู้ชม
หน้านี้มีไว้สําหรับนักพัฒนาแอปที่จะสร้างแหล่งข้อมูลของตนเองเป็นหลัก โดยไม่รับความช่วยเหลือจากคลังแหล่งข้อมูลของแผนภูมิ หากคุณใช้ไลบรารีที่จําเป็นหรือไลบรารีความช่วยเหลืออื่นๆ โปรดอ่านเอกสารประกอบของห้องสมุดก่อน
หน้านี้ยังมีไว้สําหรับผู้อ่านที่สนใจทําความเข้าใจโปรโตคอลที่ใช้สําหรับการสื่อสารกับภาพไคลเอ็นต์กับแหล่งข้อมูลด้วย
หากคุณกําลังสร้างหรือใช้การแสดงภาพ คุณไม่จําเป็นต้องอ่านหน้านี้
หากต้องการอ่านเอกสารนี้ คุณควรเข้าใจไวยากรณ์คําขอ JSON และ HTTP พื้นฐาน คุณควรทําความเข้าใจวิธีการทํางานของแผนภูมิจากมุมมองของผู้ใช้ด้วย
ภาพรวม
คุณนําโปรโตคอล Chart Tools Datasource Protocol มาเป็นผู้ให้บริการแหล่งข้อมูลสําหรับแผนภูมิของคุณเองหรือแผนภูมิอื่นๆ ได้ แหล่งข้อมูลของเครื่องมือแผนภูมิจะแสดง URL ที่เรียกว่า URL แหล่งข้อมูล ซึ่งแผนภูมิจะส่งคําขอ HTTP GET ได้ การตอบกลับดังกล่าวช่วยให้แหล่งข้อมูลแสดงข้อมูลที่จัดรูปแบบอย่างถูกต้องซึ่งแผนภูมิใช้แสดงผลกราฟิกในหน้าเว็บได้ โปรโตคอลการตอบกลับคําขอนี้เรียกว่า โปรโตคอลลวดสําหรับการแสดงภาพของ Google
ข้อมูลที่แสดงโดยแหล่งข้อมูลสามารถดึงมาจากแหล่งข้อมูลต่างๆ เช่น ไฟล์หรือฐานข้อมูล ข้อจํากัดเพียงอย่างเดียวคือคุณสามารถจัดรูปแบบข้อมูลเป็นตารางมิติข้อมูล 2 รายการที่มีคอลัมน์ที่พิมพ์
ในฐานะแหล่งข้อมูลเครื่องมือแผนภูมิ คุณต้องแยกวิเคราะห์คําขอในรูปแบบที่เฉพาะเจาะจงและส่งคืนการตอบกลับในรูปแบบที่เจาะจง ซึ่งทําได้ 2 วิธีดังนี้
-
ใช้ไลบรารีผู้ช่วยต่อไปนี้เพื่อจัดการคําขอและการตอบกลับ และสร้าง DataTable เพื่อส่งคืน หากคุณใช้ไลบรารีตัวใดตัวหนึ่งเหล่านี้ คุณเพียงแค่ต้องเขียนโค้ดที่จําเป็นต่อการทําให้ข้อมูลพร้อมใช้งานสําหรับไลบรารีในรูปแบบตารางเท่านั้น
- ไลบรารีข้อมูล Java - จัดการคําขอและการตอบสนอง สร้างตารางการตอบสนองจากข้อมูลที่คุณให้ และนําภาษาการค้นหา SQL ของ Google Chart ใช้เครื่องมือ
-
ไลบรารี Python Datasource - สร้างตารางการตอบสนองจะสร้างไวยากรณ์การตอบกลับ ไม่จัดการการแยกวิเคราะห์คําขอ หรือการใช้ภาษาการค้นหา SQL ของเครื่องมือ Google
หรือ
- เขียนแหล่งข้อมูลของคุณเองตั้งแต่ต้นโดยการจัดการคําขอ สร้างตารางข้อมูล และส่งการตอบกลับ
วิธีการทํางาน
- แหล่งข้อมูลจะแสดง URL ที่เรียกว่า URL แหล่งข้อมูล ซึ่งแผนภูมิจะส่งคําขอ HTTP GET
- ไคลเอ็นต์จะส่งคําขอ HTTP GET ด้วยพารามิเตอร์ที่อธิบายรูปแบบที่จะใช้สําหรับข้อมูลที่แสดงผล สตริงการค้นหาที่ไม่บังคับ และพารามิเตอร์ที่กําหนดเองที่ไม่บังคับ
- แหล่งข้อมูลรับและแยกวิเคราะห์คําขอตามที่อธิบายไว้ในรูปแบบคําขอ
- แหล่งข้อมูลจะเตรียมข้อมูลในรูปแบบที่ขอ ซึ่งโดยปกติแล้วจะเป็นตาราง JSON รูปแบบการตอบสนองจะอยู่ในส่วนรูปแบบการตอบกลับ แหล่งข้อมูลรองรับการใช้คําค้นหาของ API การแสดงภาพข้อมูลที่ระบุการกรอง การจัดเรียง และการบิดเบือนข้อมูลอื่นๆ
- แหล่งข้อมูลจะสร้างการตอบกลับ HTTP ที่มีข้อมูลอนุกรมและพารามิเตอร์การตอบกลับอื่นๆ และส่งกลับไปยังไคลเอ็นต์ตามที่อธิบายไว้ในรูปแบบการตอบกลับ
หมายเหตุ: พารามิเตอร์และค่าคงที่สตริงทั้งหมดที่แสดงในเอกสารนี้สําหรับคําขอและการตอบกลับ (เช่น responseHandler
และ "ตกลง") เป็นตัวพิมพ์เล็กและคํานึงถึงตัวพิมพ์เล็กและตัวพิมพ์ใหญ่
ข้อกําหนดขั้นต่ํา
ข้อกําหนดขั้นต่ําสําหรับการใช้เป็นแหล่งข้อมูลสําหรับแผนภูมิมีดังต่อไปนี้
- แหล่งข้อมูลควรยอมรับคําขอ HTTP GET และจะพร้อมใช้งานสําหรับไคลเอ็นต์
- โปรโตคอลนี้สามารถเปลี่ยนแปลงและรองรับสคีมเวอร์ชันได้ (เวอร์ชันปัจจุบันคือ 0.6) ดังนั้นแหล่งข้อมูลของคุณควรรองรับคําขอที่ใช้เวอร์ชันก่อนหน้าและเวอร์ชันปัจจุบัน คุณควรรองรับเวอร์ชันใหม่ทันทีที่มีการเผยแพร่เพื่อหลีกเลี่ยงไม่ให้ไคลเอ็นต์ที่อัปเกรดเป็นเวอร์ชันล่าสุดใช้งานได้อย่างรวดเร็ว
- อย่าหยุดหากส่งพร็อพเพอร์ตี้ที่ไม่รู้จักไปเป็นส่วนหนึ่งของคําขอ นั่นเป็นเพราะเวอร์ชันใหม่สามารถแนะนําพร็อพเพอร์ตี้ใหม่ที่คุณไม่รู้จักได้
- แยกวิเคราะห์เฉพาะพร็อพเพอร์ตี้ที่คุณคาดไว้ แม้ว่าเวอร์ชันใหม่อาจเปิดตัวพร็อพเพอร์ตี้ใหม่ อย่ายอมรับและใช้สตริงคําขอทั้งหมด โปรดแยกวิเคราะห์และใช้เฉพาะพร็อพเพอร์ตี้ที่คุณคาดไว้เพื่อป้องกันการโจมตีที่เป็นอันตราย
- บันทึกข้อกําหนดของแหล่งข้อมูลอย่างรอบคอบ หากคุณไม่ได้เขียนโค้ดแผนภูมิลูกค้าด้วยตนเอง ซึ่งรวมถึงการบันทึกข้อมูลต่อไปนี้
- พารามิเตอร์ที่กําหนดเองใดๆ ที่คุณยอมรับ
- คุณสามารถแยกวิเคราะห์ภาษาการค้นหาของ GoogleVisual API ได้หรือไม่ และ
- ประเภทข้อมูลที่คุณแสดง และโครงสร้างของข้อมูลดังกล่าว (สิ่งที่แถวและคอลัมน์แสดง รวมถึงการติดป้ายกํากับ)
- ใช้มาตรฐานด้านความปลอดภัยทั้งหมดสําหรับเว็บไซต์ที่ยอมรับคําขอจากไคลเอ็นต์ที่ไม่รู้จัก คุณรองรับ MD5, การแฮช และกลไกการรักษาความปลอดภัยอื่นๆ ในพารามิเตอร์ได้อย่างสมเหตุสมผลเพื่อตรวจสอบสิทธิ์คําขอหรือช่วยรักษาความปลอดภัยจากการโจมตีที่เป็นอันตราย และคาดหวังให้ลูกค้ารับทราบข้อกําหนดของคุณและตอบกลับ แต่อย่าลืมบันทึกข้อกําหนดทั้งหมดไว้อย่างถูกต้อง หากไม่ได้เขียนโค้ดแผนภูมิด้วยตนเอง ดูข้อควรพิจารณาด้านความปลอดภัยด้านล่าง
- สตริงคําขอและการตอบกลับทั้งหมดควรเข้ารหัสแบบ UTF-8
- รูปแบบการตอบกลับที่สําคัญที่สุดคือ JSON อย่าลืมใช้ JSON ก่อนเนื่องจากเป็นรูปแบบที่แผนภูมิส่วนใหญ่ใช้ เพิ่มการตอบกลับประเภทอื่นๆ หลังจากนั้น
- คุณไม่จําเป็นต้องรองรับภาษาของคําค้นหา API การแสดงภาพ แต่แหล่งข้อมูลจะมีประโยชน์มากขึ้นสําหรับลูกค้า
- คุณไม่จําเป็นต้องรองรับคําขอจากแผนภูมิทุกประเภทและทุกประเภท และรองรับพารามิเตอร์ที่กําหนดเองสําหรับแผนภูมิที่กําหนดเองได้ แต่คุณควรแสดงผลคําตอบในรูปแบบมาตรฐานที่อธิบายไว้ด้านล่าง
ข้อควรพิจารณาด้านความปลอดภัย
เมื่อออกแบบแหล่งข้อมูล คุณต้องคํานึงถึงความปลอดภัยของข้อมูล คุณสามารถใช้รูปแบบการรักษาความปลอดภัยที่หลากหลายสําหรับเว็บไซต์ได้ ตั้งแต่การเข้าถึงรหัสผ่านง่ายๆ ไปจนถึงการตรวจสอบสิทธิ์คุกกี้ที่ปลอดภัย
XSSI (การรวมสคริปต์ข้ามเว็บไซต์) มีความเสี่ยงจากแผนภูมิ ผู้ใช้อาจไปที่หน้าที่มีสคริปต์ที่เป็นอันตรายซึ่งเริ่มดําเนินการค้นหา URL แหล่งข้อมูลโดยใช้ข้อมูลเข้าสู่ระบบของผู้ใช้ปัจจุบัน หากผู้ใช้ไม่ได้ออกจากระบบเว็บไซต์ สคริปต์จะได้รับการตรวจสอบสิทธิ์ว่าเป็นผู้ใช้ปัจจุบันและมีสิทธิ์ในเว็บไซต์นั้น การใช้แท็ก <script src> สคริปต์ที่เป็นอันตรายอาจรวมแหล่งข้อมูลที่คล้ายกับ JSONP
เพื่อเพิ่มระดับการรักษาความปลอดภัย คุณอาจพิจารณาจํากัดคําขอที่มาจากโดเมนเดียวกับแหล่งข้อมูลของคุณ การดําเนินการนี้จะจํากัดการเปิดเผยแหล่งข้อมูลของคุณเป็นอย่างมาก แต่หากมีข้อมูลที่ละเอียดอ่อนมากซึ่งไม่ควรเข้าถึงจากภายนอกโดเมน คุณควรพิจารณา แหล่งข้อมูลที่อนุญาตให้เฉพาะคําขอจากโดเมนเดียวกันเรียกว่าแหล่งข้อมูลที่ถูกจํากัด ซึ่งต่างจากแหล่งข้อมูลที่ไม่จํากัด ซึ่งจะยอมรับการค้นหาจากโดเมนใดก็ได้ รายละเอียดเกี่ยวกับวิธีใช้แหล่งข้อมูลที่ถูกจํากัดมีดังนี้
เพื่อให้มั่นใจว่าคําขอมาจากภายในโดเมนของคุณจริงๆ และไม่ได้มาจากโดเมนภายนอก (หรือเบราว์เซอร์ภายในโดเมนที่อยู่ภายใต้การโจมตี XSRF) ให้ทําดังนี้
- ยืนยันว่ามีส่วนหัว "X-DataSource-Auth" ในคําขอ ส่วนหัวนี้กําหนดโดย GoogleVisual API คุณไม่จําเป็นต้องตรวจสอบเนื้อหาของส่วนหัวนี้ เพียงยืนยันว่ามีส่วนหัวดังกล่าวเท่านั้น หากใช้ไลบรารีแหล่งข้อมูลของ Google เครื่องมือแผนภูมิ คุณให้ไลบรารีจัดการเรื่องนี้ได้
- ใช้การตรวจสอบสิทธิ์คุกกี้เพื่อตรวจสอบสิทธิ์ไคลเอ็นต์ คุณไม่สามารถแทรกส่วนหัวที่กําหนดเองลงในคําขอข้ามโดเมนในขณะที่ยังคงเก็บคุกกี้การตรวจสอบสิทธิ์ไว้
- ทําให้ JavaScript ไม่มีแนวโน้มที่จะทํางานเมื่อรวมอยู่ในแท็ก <script src> หากต้องการทําเช่นนี้ ให้ใส่ ) }} ต่อท้ายการตอบสนอง JSON แล้วตามด้วยบรรทัดใหม่ ในไคลเอ็นต์ นําคํานําหน้าออกจากการตอบกลับ สําหรับ XmlHttpRequest จะทําได้เฉพาะเมื่อคําขอนั้นมาจากโดเมนเดียวกัน
รูปแบบคําขอ
ไคลเอ็นต์จะส่งคําขอ HTTP GET ที่มีพารามิเตอร์หลายรายการ ซึ่งรวมถึงองค์ประกอบที่กําหนดเอง สตริงการค้นหาที่ไม่บังคับ ลายเซ็น และองค์ประกอบอื่นๆ คุณมีหน้าที่แยกวิเคราะห์พารามิเตอร์ที่อธิบายไว้ในส่วนนี้เท่านั้น และควรระมัดระวังไม่จัดการผู้อื่นเพื่อหลีกเลี่ยงการโจมตีที่เป็นอันตราย
โปรดตรวจสอบว่าคุณมีค่าเริ่มต้นสําหรับพารามิเตอร์ที่ไม่บังคับ (ทั้งแบบมาตรฐานและกําหนดเอง) และจัดทําเอกสารเริ่มต้นทั้งหมดไว้ในเอกสารประกอบของเว็บไซต์
ต่อไปนี้คือตัวอย่างคําขอ (ดูตัวอย่างเพิ่มเติมและตัวอย่างการตอบกลับได้ที่ส่วนท้ายของเอกสารนี้ในตัวอย่าง)
หมายเหตุ: สตริงคําขอต่อไปนี้และสตริงที่แสดงในส่วนตัวอย่างควรกําหนดเป็นอักขระหลีกกับ URL ก่อนส่ง
Basic request, no parameters: http://www.example.com/mydatasource Request with the tqx parameter that contains two properties: http://www.example.com/mydatasource?tqx=reqId:0;sig:4641982796834063168 Request with a query string: http://www.example.com/mydatasource?tq=limit 1
รายการพารามิเตอร์มาตรฐานทั้งหมดในสตริงคําขอมีดังนี้ โปรดทราบว่าทั้งชื่อพารามิเตอร์ (เช่น "เวอร์ชัน") และค่าสตริงคงที่ (เช่น "ok", "warning" และ "not_modified") คํานึงถึงตัวพิมพ์เล็กและตัวพิมพ์ใหญ่ ตารางนี้ยังอธิบายว่าต้องส่งพารามิเตอร์หรือไม่และต้องส่งหรือไม่ หากจําเป็นต้องส่ง
พารามิเตอร์ | ต้องการในคําขอไหม |
ต้องจัดการแหล่งข้อมูลหรือไม่ |
คำอธิบาย |
---|---|---|---|
tq | ไม่ได้ |
ไม่ได้ |
คําค้นหาที่เขียนในภาษาการค้นหา Google API การแสดงภาพ ซึ่งระบุวิธีกรอง จัดเรียง หรือจัดการกับข้อมูลที่แสดงผล สตริงนี้ไม่ต้องใส่เครื่องหมายคําพูด เช่น |
tqx | ไม่ได้ |
ได้ |
ชุดคู่คีย์/ค่าที่คั่นด้วยโคลอนสําหรับพารามิเตอร์มาตรฐานหรือที่กําหนดเอง การจับคู่จะคั่นด้วยเครื่องหมายเซมิโคลอน รายการพารามิเตอร์มาตรฐานที่กําหนดโดยโปรโตคอลการแสดงภาพมีดังนี้
เช่น |
tqrt | ไม่ได้ |
ไม่ได้ |
สงวนไว้: ไม่สนใจพารามิเตอร์นี้ วิธีการที่ใช้ส่งคําค้นหา |
รูปแบบการตอบกลับ
รูปแบบการตอบสนองจะขึ้นอยู่กับพารามิเตอร์ out
ของคําขอ ซึ่งระบุประเภทของการตอบกลับที่คาดไว้ ดูวิธีตอบกลับคําขอแต่ละประเภทได้ที่ส่วนต่อไปนี้
- JSON - แสดงผลการตอบสนองของ JSON ที่มีข้อมูลในออบเจ็กต์ JavaScript ที่ส่งผ่านไปยังเครื่องมือสร้าง
DataTable
ได้โดยตรงเพื่อป้อนข้อมูล คําขอประเภทนี้เป็นคําขอที่พบบ่อยที่สุดและมีความสําคัญมากที่สุดในการใช้งานอย่างเหมาะสม - CSV - แสดงผลรายการค่าที่คั่นด้วยคอมมาเพื่อให้เบราว์เซอร์จัดการ
- TSV - ส่งกลับรายการค่าที่คั่นด้วยแท็บเพื่อให้เบราว์เซอร์จัดการ
- HTML - แสดงผลตาราง HTML ที่เบราว์เซอร์จะแสดงผล
คุณใช้ไลบรารีแหล่งข้อมูลภาพของ Google (java) หรือไลบรารี Python แบบแสดงภาพเพื่อสร้างรูปแบบเอาต์พุตเหล่านี้ให้คุณได้
รูปแบบการตอบสนองของ JSON
รูปแบบการตอบสนองเริ่มต้นคือ JSON หากคําขอมีส่วนหัว "X-DataSource-Auth" และ JSONP โปรดทราบว่าจริงๆ แล้วไคลเอ็นต์แผนภูมิ Google รองรับ JSON และ JSONP เวอร์ชันที่แก้ไขแล้ว หากคุณใช้ไลบรารีผู้ช่วย Java หรือ Python ไคลเอ็นต์จะใส่โค้ดที่เหมาะสมให้คุณ หากคุณแยกวิเคราะห์การตอบกลับด้วยตนเอง โปรดดูการแก้ไข JSON ด้านล่าง
หากคุณกําลังบังคับใช้คําขอโดเมนเดียวกัน คุณควรยืนยันว่ามีส่วนหัว "X-DataSource-Auth" ในคําขอและใช้คุกกี้เพื่อให้สิทธิ์
นี่คือรูปแบบการตอบสนองเดียวที่เมธอด Googleการแสดงภาพ API ระบุไว้
google.visualization.Query.send()
ดูตัวอย่างคําขอและ JSON ได้ที่ท้ายหน้านี้ในตัวอย่าง
คุณอาจใช้ไลบรารีผู้ช่วย Java หรือ Python เพื่อสร้างสตริงคําตอบนี้ให้กับคุณ
รูปแบบการตอบกลับนี้คือออบเจ็กต์ JSON ที่เข้ารหัสแบบ UTF-8 (ออบเจ็กต์ที่อยู่ภายใต้วงเล็บปีกกา { } ด้วยพร็อพเพอร์ตี้แต่ละรายการที่คั่นด้วยคอมมา) ซึ่งมีพร็อพเพอร์ตี้ในตารางด้านล่าง (กําหนดข้อมูลลงในพร็อพเพอร์ตี้ table
) ออบเจ็กต์ JSON นี้ควรรวมอยู่ในค่าพารามิเตอร์ responseHandler
จากคําขอ ดังนั้นหากค่า responseHandler
ของคําขอคือ "myHandler" คุณควรแสดงผลสตริงแบบนี้ (มีพร็อพเพอร์ตี้เพียงรายการเดียวที่แสดงความสั้นกระชับ)
"myHandler({status:ok, ...})"
หากคําขอไม่มีค่า responseHandler
ค่าเริ่มต้นจะเป็น "google.visualization.Query.setResponse" คุณจึงควรแสดงผลสตริงเช่นนี้ (พร็อพเพอร์ตี้เพียง 1 รายการที่แสดงสั้นกระชับ)
"google.visualization.Query.setResponse({status:ok, ...})"
สมาชิกออบเจ็กต์การตอบกลับที่พร้อมใช้งานมีดังต่อไปนี้
พร็อพเพอร์ตี้ | จำเป็นไหม |
คำอธิบาย |
---|---|---|
เวอร์ชัน | ไม่ได้ |
หมายเลขสตริงที่ระบุหมายเลขเวอร์ชันโปรโตคอลการโอนเงินผ่านธนาคารของ Google การแสดงภาพ หากไม่ได้ระบุ ไคลเอ็นต์จะถือว่าเวอร์ชันล่าสุด เช่น |
รหัสคําขอ | มี* |
หมายเลขสตริงที่ระบุรหัสของคําขอนี้สําหรับไคลเอ็นต์นี้ หากอยู่ในคําขอ ให้แสดงค่าเดียวกัน ดูรายละเอียดได้ที่ reqId ในส่วนคําขอ * หากไม่ได้ระบุพารามิเตอร์นี้ในคําขอ คุณไม่ต้องตั้งค่าในการตอบสนอง |
สถานะ | ได้ |
สตริงที่อธิบายความสําเร็จหรือล้มเหลวของการดําเนินการนี้ ต้องเป็นค่าใดค่าหนึ่งต่อไปนี้
เช่น |
คำเตือน | เฉพาะในกรณีที่ status=warning |
อาร์เรย์ของออบเจ็กต์อย่างน้อย 1 รายการที่อธิบายปัญหาที่ไม่ร้ายแรง
ต้องระบุหาก
เช่น |
ข้อผิดพลาด | ต้องระบุหาก status=error |
อาร์เรย์ของออบเจ็กต์อย่างน้อย 1 รายการ ซึ่งแต่ละรายการอธิบายข้อผิดพลาด ต้องระบุ
อาร์เรย์มีสมาชิกสตริงต่อไปนี้ (แสดงผลเพียงค่าเดียวสําหรับสมาชิกแต่ละราย)
ตัวอย่าง:
|
Sig | ไม่ได้ |
ค่าที่แฮชของออบเจ็กต์ตาราง มีประโยชน์สําหรับการเพิ่มประสิทธิภาพการโอนข้อมูลระหว่างไคลเอ็นต์กับแหล่งข้อมูล คุณเลือกอัลกอริทึมแฮชใดก็ได้ที่ต้องการ หากคุณรองรับพร็อพเพอร์ตี้นี้ คุณควรแสดงผลค่าที่ส่งโดยไคลเอ็นต์หากไม่มีการส่งคืนข้อมูล หรือแสดงแฮชใหม่หากมีการส่งคืนข้อมูลใหม่ เช่น |
ตาราง | ไม่ได้ |
ออบเจ็กต์ {cols:[{id:'Col1',label:'',type:'number'}], rows:[{c:[{v:1.0,f:'1'}]}, {c:[{v:2.0,f:'2'}]}, {c:[{v:3.0,f:'3'}]}, {c:[{v:1.0,f:'1'}]} ] } พร็อพเพอร์ตี้ ตัวอย่าง: ดูตัวอย่างด้านล่าง |
ไลบรารีผู้ช่วยของ Google และคําค้นหาทั้งหมดที่ส่งไปยัง Google จะแสดง JSON/JSONP ที่เข้มงวด
หากคุณไม่ได้แยกวิเคราะห์
โค้ดที่ส่งคืนด้วยตนเอง คุณไม่ควรดําเนินการใดๆ หากใช่ คุณสามารถใช้ JSON.parse()
เพื่อแปลงสตริง JSON เป็นออบเจ็กต์ JavaScript ได้ ความแตกต่างของวิธีประมวลผล JSON ของ API คือ แม้ว่า JSON จะไม่รองรับค่าวันที่ของ JavaScript (เช่น "วันที่ใหม่(2008,1,28,0,31,26)", API รองรับการแสดงวันที่ที่ถูกต้องของ JSON เป็นสตริงในรูปแบบ Date(year, month, day[,hour, minute, second[, millisecond]])
ซึ่งแต่ละตัวเลือกเป็นแบบวันหลังหรือไม่ก็ได้ และ เดือนเป็นแบบ 0
การเพิ่มประสิทธิภาพการตอบกลับ JSON
หากลูกค้าส่งคําขอ 2 รายการ และข้อมูลไม่มีการเปลี่ยนแปลงระหว่างคําขอ ก็ไม่ควรส่งข้อมูลซ้ํา เนื่องจากจะทําให้สิ้นเปลืองแบนด์วิดท์ เพื่อให้โปรโตคอลมีประสิทธิภาพมากขึ้น โปรโตคอลจะรองรับการแคชข้อมูลในไคลเอ็นต์ และส่งสัญญาณในการตอบสนองหากข้อมูลไม่มีการเปลี่ยนแปลงตั้งแต่คําขอล่าสุด ต่อไปนี้เป็นวิธีดำเนินการ
- ไคลเอ็นต์ส่งคําขอไปยังแหล่งข้อมูล
- แหล่งข้อมูลจะสร้าง
DataTable
รวมถึงแฮชของออบเจ็กต์DataTable
และแสดงผลทั้ง 2 แบบในการตอบกลับ (ระบบจะส่งคืนแฮชในพารามิเตอร์tqx.
sig
) ไคลเอ็นต์ GoogleVisual API จะแคชค่าDataTable
และsig
- ไคลเอ็นต์ส่งคําขอข้อมูลอีกครั้ง รวมถึงค่า
tqx.sig
ที่แคชไว้ - แหล่งข้อมูลตอบกลับได้ 2 วิธีดังนี้
- หากข้อมูลมีการเปลี่ยนแปลงจากคําขอก่อนหน้า แหล่งข้อมูลจะส่งแฮช
DataTable
รายการใหม่และแฮชsig
ค่าใหม่ - หากข้อมูลไม่มีการเปลี่ยนแปลงจากคําขอก่อนหน้า แหล่งข้อมูลจะส่ง
status=error
,reason=not_modified
และsig=old_sig_value
กลับมา
- หากข้อมูลมีการเปลี่ยนแปลงจากคําขอก่อนหน้า แหล่งข้อมูลจะส่งแฮช
- ทั้ง 2 กรณี หน้าที่โฮสต์แผนภูมินั้นจะได้รับการตอบกลับที่สําเร็จ และจะเรียกข้อมูล
DataTable
ได้โดยการเรียกใช้QueryResponse.getDataTable()
หากข้อมูลเหมือนกัน ข้อมูลจะเป็นเพียงเวอร์ชันที่แคชไว้ของตาราง
โปรดทราบว่าวิธีนี้ใช้ได้เฉพาะกับคําขอ JSON จากแผนภูมิที่สร้างใน GoogleVisual API
รูปแบบการตอบกลับ CSV
หากคําขอระบุ out:csv
การตอบสนองจะไม่มีข้อมูลเมตา แต่เป็นเพียงการแทนข้อมูล CSV โดยปกติแล้วตาราง CSV จะเป็นรายการที่คั่นด้วยคอมมา ซึ่งแถวข้อมูลแต่ละแถวจะเป็นลิสต์ค่าที่คั่นด้วยคอมมา ซึ่งลงท้ายด้วยอักขระขึ้นบรรทัดใหม่ของ UNIX (\n) ค่าของเซลล์ควรมีประเภทเดียวกันในแต่ละคอลัมน์ แถวแรกคือป้ายกํากับคอลัมน์ ต่อไปนี้คือตัวอย่างของตาราง 3 แถว 3 คอลัมน์
A, B, C 1.0, "yes", true 2.0, "no", false 3.0, "maybe", true
โปรโตคอลนี้ไม่ได้ระบุรูปแบบ CSV แต่แหล่งข้อมูลนั้นๆ มีหน้าที่กําหนดรูปแบบ CSV แต่รูปแบบทั่วไปคือชุดค่าที่คั่นด้วยคอมมา (ไม่ต้องเว้นวรรค) และบรรทัดใหม่ (\n) ที่ท้ายแถวทุกแถว เมื่อเบราว์เซอร์ได้รับการตอบกลับสตริง CSV เบราว์เซอร์อาจถามผู้ใช้ว่าจะใช้แอปพลิเคชันใดเพื่อเปิดสตริง หรือเพียงแค่แสดงผลบนหน้าจอ ไลบรารีแบบโอเพนซอร์สของ Java และ Python มีวิธีแปลงตารางข้อมูลเป็นสตริง CSV
หากคําขอมีสมาชิก outFileName
ของพารามิเตอร์ tqx
คุณควรพยายามใส่ชื่อไฟล์ที่ระบุในส่วนหัวการตอบกลับ
ออบเจ็กต์ google.visualization.Query
ไม่รองรับคําขอการตอบกลับ CSV หากลูกค้าต้องการขอ CSV คุณจะฝังแกดเจ็ตแถบเครื่องมือการแสดงภาพในหน้าเว็บได้ หรือจะใช้โค้ดที่กําหนดเองเพื่อสร้างคําขอ หรือจะใส่ลิงก์ที่ตั้งพร็อพเพอร์ตี้ out:csv
ของ tqx
อย่างชัดเจนก็ได้ ดังที่แสดงใน URL คําขอต่อไปนี้
คำขอ
http://www.example.com/mydatasource?tqx=reqId:1;out:csv
คําตอบ
Label 1,Label2\n1,a\n2,b\n3,c\n4,d
รูปแบบการตอบกลับ TSV
หากคําขอระบุ out:tsv-excel
การตอบสนองจะไม่มีข้อมูลเมตา แต่เป็นเพียงการนําเสนอข้อมูลแบบคั่นด้วยแท็บ ซึ่งก็คือการเข้ารหัส utf-16 หากคําขอมีสมาชิก outFileName
ของพารามิเตอร์ tqx
คุณควรพยายามใส่ชื่อไฟล์ที่ระบุในส่วนหัวการตอบกลับ
รูปแบบการตอบกลับ HTML
หากคําขอระบุ out:html
การตอบกลับควรเป็นหน้า HTML ที่กําหนดตาราง HTML ที่มีข้อมูล วิธีนี้มีประโยชน์ในการแก้ไขข้อบกพร่องของโค้ด เนื่องจากเบราว์เซอร์สามารถแสดงผลในรูปแบบที่อ่านได้โดยตรง คุณส่งคําค้นหาสําหรับการตอบกลับ HTML โดยใช้ออบเจ็กต์ google.visualization.Query
ไม่ได้
คุณต้องค้นหาการตอบกลับ HTML โดยใช้โค้ดที่กําหนดเอง หรือพิมพ์ URL ที่คล้ายกับ URL นี้ในเบราว์เซอร์
คำขอ
http://www.example.com/mydatasource?tqx=reqId:1;out:html
คําตอบ
<html><body><table border='1' cellpadding='2' cellspacing='0'><tr style='font-weight: bold; background-color: #aaa;'><td>label 1</td><td>label 2</td></tr><tr bgcolor='#f0f0f0'><td align='right'>1</td><td>a</td></tr><tr bgcolor='#ffffff'><td align='right'>2</td><td>b</td></tr><tr bgcolor='#f0f0f0'><td align='right'>3</td><td>c</td></tr><tr bgcolor='#ffffff'><td align='right'>4</td><td>d</td></tr></table></body></html>
ตัวอย่าง
ตัวอย่างคําขอและการตอบกลับมีดังนี้ โปรดทราบว่าคําขอไม่ได้ใช้ Escape กับ URL ซึ่งมักจะทําโดยเบราว์เซอร์หรือออบเจ็กต์ google.visualization.Query
คําขอแบบง่าย: แสดงข้อมูลพื้นฐานด้วยคอลัมน์ 3 คอลัมน์ 4 แถว
Request: http://www.example.com/mydatasource Response google.visualization.Query.setResponse({version:'0.6',reqId:'0',status:'ok',sig:'5982206968295329967',table:{cols:[{id:'Col1',label:'',type:'number'},{id:'Col2',label:'',type:'number'},{id:'Col3',label:'',type:'number'}],rows:[{c:[{v:1.0,f:'1'},{v:2.0,f:'2'},{v:3.0,f:'3'}]},{c:[{v:2.0,f:'2'},{v:3.0,f:'3'},{v:4.0,f:'4'}]},{c:[{v:3.0,f:'3'},{v:4.0,f:'4'},{v:5.0,f:'5'}]},{c:[{v:1.0,f:'1'},{v:2.0,f:'2'},{v:3.0,f:'3'}]}]}});
คําขอแบบง่ายที่มีเครื่องจัดการการตอบกลับ: แสดงคอลัมน์ 3 คอลัมน์และตาราง 3 แถวที่มีข้อมูลประเภทต่างๆ
Request: http://www.example.com/mydatasource?tqx=responseHandler:myHandlerFunction Response myHandlerFunction({version:'0.6',reqId:'0',status:'ok',sig:'4641982796834063168',table:{cols:[{id:'A',label:'NEW A',type:'string'},{id:'B',label:'B-label',type:'number'},{id:'C',label:'C-label',type:'datetime'}],rows:[{c:[{v:'a'},{v:1.0,f:'1'},{v:new Date(2008,1,28,0,31,26),f:'2/28/08 12:31 AM'}]},{c:[{v:'b'},{v:2.0,f:'2'},{v:new Date(2008,2,30,0,31,26),f:'3/30/08 12:31 AM'}]},{c:[{v:'c'},{v:3.0,f:'3'},{v:new Date(2008,3,30,0,31,26),f:'4/30/08 12:31 AM'}]}]}});
การค้นหาที่มีสตริงคําค้นหาแบบง่าย: ขอคอลัมน์เดียวเพื่อแสดงคอลัมน์เดียวที่มี 4 แถว
Request: http://www.example.com/mydatasource?tq=select Col1 Response: google.visualization.Query.setResponse({version:'0.6',reqId:'0',status:'ok',sig:'6099996038638149313',table:{cols:[{id:'Col1',label:'',type:'number'}],rows:[{c:[{v:1.0,f:'1'}]},{c:[{v:2.0,f:'2'}]},{c:[{v:3.0,f:'3'}]},{c:[{v:1.0,f:'1'}]}]}});
ข้อผิดพลาดของข้อมูลที่ไม่ได้แก้ไข: ตัวอย่างข้อผิดพลาด not_modified
Request: http://www.example.com/mydatasource?tqx=reqId:0;sig:4641982796834063168 Response: google.visualization.Query.setResponse({version:'0.6',reqId:'0',status:'error',errors:[{reason:'not_modified',message:'Data not modified'}]});
คําเตือนการตัดข้อมูล: ตัวอย่างคําเตือน data_truncated
โปรดทราบว่าคําขอยังคงส่งคืนข้อมูลอยู่
Request: http://www.example.com/mydatasource?tq=limit 1 Response: google.visualization.Query.setResponse({version:'0.6',reqId:'0',status:'warning',warnings:[{reason:'data_truncated',message:'Retrieved data was truncated'}],sig:'1928724788649668508',table:{cols:[{id:'A',label:'NEW A',type:'string'},{id:'B',label:'B-label',type:'number'},{id:'C',label:'C-label',type:'datetime'}],rows:[{c:[{v:'a'},{v:1.0,f:'1'},{v:new Date(2008,1,28,0,31,26),f:'2/28/08 12:31 AM'}]}]}});
ข้อผิดพลาดเกี่ยวกับการเข้าถึงถูกปฏิเสธ: ตัวอย่างข้อผิดพลาด access_denied
Request: http://www.example.com/mydatasource Response: google.visualization.Query.setResponse({version:'0.6',reqId:'0',status:'error',errors:[{reason:'access_denied',message:'Access denied',detailed_message:'Access Denied'}]});
สตริงคําค้นหาไม่ถูกต้อง: ตัวอย่างคําขอที่มีสตริงคําค้นหาที่ไม่ถูกต้อง โปรดทราบว่าข้อความโดยละเอียดเป็นข้อความทั่วไปแทนที่จะเป็นข้อความแสดงข้อผิดพลาดจริง
Request: http://www.example.com/mydatasource?tq=select A Response: google.visualization.Query.setResponse({version:'0.6',reqId:'0',status:'error',errors:[{reason:'invalid_query',message:'Invalid query',detailed_message:'Bad query string.'}]});
เครื่องมือสำหรับการพัฒนา
- ไลบรารี JavaScript ของ Java (จาก Google) - จัดการคําขอและการตอบสนอง สร้างตารางการตอบสนองจากข้อมูลที่คุณระบุ และใช้ภาษาการค้นหา SQL สําหรับ Google Chart Tools
- ไลบรารี Python Datasource (จาก Google) - สร้างตารางการตอบสนองจะสร้างไวยากรณ์การตอบกลับ ไม่จัดการการแยกวิเคราะห์คําขอ หรือการใช้ภาษาการค้นหา SQL ของ Google เครื่องมือแผนภูมิ
- MC-Google_Visualization (บุคคลที่สาม) - เป็นไลบรารีฝั่งเซิร์ฟเวอร์สําหรับ PHP ที่คุณสามารถใช้เพื่อนําแหล่งข้อมูลของแผนภูมิไปใช้กับเครื่องมือฐานข้อมูล MySQL, SQLite และ PostgreSQL โดยใช้ PDO
- bortosky-google-visualization (บุคคลที่สาม) - เป็นไลบรารีผู้ช่วยเพื่อสร้างตารางข้อมูล Google APIs API สําหรับผู้ใช้ .NET
- สตรีมเมอร์ GV (บุคคลที่สาม) - GV Streamer เป็นเครื่องมือฝั่งเซิร์ฟเวอร์ที่แปลงข้อมูลจากแหล่งที่มาต่างๆ เป็นการตอบกลับการค้นหาที่ถูกต้องไปยังแผนภูมิของ Google ได้ สตรีมเมอร์ GV รองรับหลายภาษา (เช่น PHP, Java, .NET) และแหล่งข้อมูลดิบหลายแห่ง (เช่น MySql)
- TracGViz (บุคคลที่สาม) - TracGViz เป็นเครื่องมือโอเพนซอร์สฟรีที่จัดหาคอมโพเนนต์เพื่อให้ Trac สามารถใช้แกดเจ็ตแผนภูมิได้ รวมถึงใช้ข้อมูลที่จัดการโดย Trac เป็นแหล่งข้อมูลของ Google Chart เป็นแหล่งข้อมูล
- vis-table (บุคคลที่สาม) - ไลบรารีที่ใช้แหล่งข้อมูลเครื่องมือแผนภูมิของ Google ใน PHP ซึ่งประกอบด้วย 3 ส่วนหลัก การใช้งานตารางข้อมูล โปรแกรมแยกวิเคราะห์ภาษาของคําค้นหา และเครื่องมือจัดรูปแบบ
- การใช้แหล่งข้อมูล Google ใน Oracle PL/SQL (บุคคลที่สาม) - แพ็กเกจ Oracle PL/SQL ที่ช่วยให้ Oracle เซิร์ฟเวอร์แหล่งข้อมูลเซิร์ฟเวอร์มาจากฐานข้อมูลโดยตรง โดยทั่วไปแล้ว คุณจะใช้การค้นหา Oracle เป็นแหล่งข้อมูลของ Google Chart ได้ (แพ็กเกจจะแสดงไฟล์ JSON ที่มีข้อมูล) มีการรองรับ Google Query Language อย่างเต็มรูปแบบ