資料來源 Python 程式庫

Google 提供開放原始碼的 Python 程式庫，可建立 DataTable 物件以視覺化方式使用。這個程式庫可用於在 Python 中建立 DataTable，並以下列三種格式中的任一種輸出：

  • JSON 字串 ：如果您託管的網頁代管使用您資料的視覺化呈現方式，您可以產生 JSON 字串並傳遞至 DataTable 建構函式來填入資料。
  • JSON 回應 ：如果您未代管代管視覺化功能的網頁，而只是想做為外部視覺化的資料來源，則可以建立完整的 JSON 回應字串，這個字串可以在回應資料要求時傳回。
  • JavaScript 字串：您可以將資料表輸出為包含幾行 JavaScript 程式碼的字串。這個字串會建立 google.visualization.DataTable 物件，並填入 Python 資料表中的資料。然後在引擎中執行這個 JavaScript，即可產生並填入 google.visualization.DataTable 物件。通常用於偵錯。

本文假設您已瞭解基本的 Python 程式設計，並已參閱入門指南說明文件，瞭解如何 建立視覺化內容及使用視覺化內容。

按這裡可使用 Python 程式庫。

目錄

如何使用媒體庫

以下是基本步驟的詳細說明：

1. 建立 gviz_api.DataTable 物件

從上方連結匯入 gviz_api.py 程式庫，並對 gviz_api.DataTable 類別執行個體化。這個類別使用兩個參數：資料表結構定義 (說明資料表的資料格式)，以及用來填入資料表的選用資料。之後，您可以視需要新增資料，或是完全覆寫資料，但無法移除個別資料列，或是清除資料表結構定義。

2. 說明資料表結構定義

表格結構定義是由傳遞至建構函式的 table_description 參數指定。設定後即無法變更。結構定義說明資料表中的所有資料欄，包括各資料欄的資料類型、ID 和選用標籤。

每一欄都會以元組 (ID [,data_type [,label [,custom_properties]]) 表示)。

  • ID - 用來識別資料欄的字串 ID。可包含空格。 每個資料欄的 ID 不得重複。
  • data_type - [選用] 是該欄資料之 Python 資料類型的字串描述元。您可以在 SingleValueToJS() 方法中找到支援的資料類型清單。例如「string」和「boolean」。 如未指定，則預設值為「string」。
  • label - 易記的資料欄名稱，可能會顯示為以視覺呈現的一部分。如未指定，則會使用 ID 值。
  • custom_properties - 自訂欄屬性的 {String:String} 字典。

資料表結構定義是資料欄描述元元組的集合。每位清單成員、字典鍵或字典值都必須為另一個集合或描述元元組。您可以使用任何字典或清單的組合，但每個鍵、值或成員最終都必須評估為描述元元組。以下列舉幾個例子。

  • 欄清單：[('a', 'number'), ('b', 'string')]
  • Dictionary of lists: {('a', 'number'): [('b', 'number'), ('c', 'string')]}
  • Dictionary of dictionaries: {('a', 'number'): {'b': 'number', 'c': 'string'}}
  • 依此類推，任意層級的巢狀結構依此類推。

3. 填入資料

如要將資料新增至資料表，請使用與資料表結構定義相同的結構，建立資料元素結構。舉例來說，如果您的結構定義為清單，資料就必須是清單：

  • schema: [("color", "string"), ("shape", "string")]
  • 資料：[["藍色", "正方形"]、["紅色", "圓形"]]

如果結構定義是字典，資料必須是字典：

  • schema: {("rowname", "string"): [("color", "string"), ("shape", "string")] }
  • 資料：{"row1": ["blue", "square"], "row2": ["紅色", "圓形"]}

表格列是對應資料和結構定義的一部分，以下舉例說明將兩個資料欄清單的結構定義套用至兩列資料時。

Schema:[(color),(shape)]
            /     \       
Data: [["blue", "square"], ["red", "circle"]]

Table: 
      Color    Shape
      blue     square
      red      circle

請注意，這裡的字典索引鍵評估的是資料欄資料。您可以在程式碼的 AttachData() 方法說明文件中，找到更複雜的範例。我們之所以允許這類複雜的巢狀結構，是為了讓您使用符合需求的 Python 資料結構。

4. 輸出資料

最常見的輸出格式是 JSON，因此您可能會使用 ToJsonResponse() 函式建立要傳回的資料。不過，如果您剖析了輸入要求，並支援不同的輸出格式，您可以呼叫任何其他輸出方法以傳回其他格式，包括逗號分隔值、定位點分隔值和 JavaScript。JavaScript 通常僅用於偵錯。請參閱「實作資料來源」一文，瞭解如何處理要求來取得偏好的回應格式。

使用範例

以下列舉幾個例子，示範如何使用各種輸出格式。

ToJSon 和 ToJS 範例

#!/usr/bin/python

import gviz_api

page_template = """
<html>
  <script src="https://www.gstatic.com/charts/loader.js"></script>
  <script>
    google.charts.load('current', {packages:['table']});

    google.charts.setOnLoadCallback(drawTable);
    function drawTable() {
      %(jscode)s
      var jscode_table = new google.visualization.Table(document.getElementById('table_div_jscode'));
      jscode_table.draw(jscode_data, {showRowNumber: true});

      var json_table = new google.visualization.Table(document.getElementById('table_div_json'));
      var json_data = new google.visualization.DataTable(%(json)s, 0.6);
      json_table.draw(json_data, {showRowNumber: true});
    }
  </script>
  <body>
    <H1>Table created using ToJSCode</H1>
    <div id="table_div_jscode"></div>
    <H1>Table created using ToJSon</H1>
    <div id="table_div_json"></div>
  </body>
</html>
"""

def main():
  # Creating the data
  description = {"name": ("string", "Name"),
                 "salary": ("number", "Salary"),
                 "full_time": ("boolean", "Full Time Employee")}
  data = [{"name": "Mike", "salary": (10000, "$10,000"), "full_time": True},
          {"name": "Jim", "salary": (800, "$800"), "full_time": False},
          {"name": "Alice", "salary": (12500, "$12,500"), "full_time": True},
          {"name": "Bob", "salary": (7000, "$7,000"), "full_time": True}]

  # Loading it into gviz_api.DataTable
  data_table = gviz_api.DataTable(description)
  data_table.LoadData(data)

  # Create a JavaScript code string.
  jscode = data_table.ToJSCode("jscode_data",
                               columns_order=("name", "salary", "full_time"),
                               order_by="salary")
  # Create a JSON string.
  json = data_table.ToJSon(columns_order=("name", "salary", "full_time"),
                           order_by="salary")

  # Put the JS code and JSON string into the template.
  print "Content-type: text/html"
  print
  print page_template % vars()


if __name__ == '__main__':
  main()

ToJSonResponse 範例

遠端用戶端會在資料要求中使用 JSonResponse。

#!/usr/bin/python

import gviz_api

description = {"name": ("string", "Name"),
               "salary": ("number", "Salary"),
               "full_time": ("boolean", "Full Time Employee")}
data = [{"name": "Mike", "salary": (10000, "$10,000"), "full_time": True},
        {"name": "Jim", "salary": (800, "$800"), "full_time": False},
        {"name": "Alice", "salary": (12500, "$12,500"), "full_time": True},
        {"name": "Bob", "salary": (7000, "$7,000"), "full_time": True}]

data_table = gviz_api.DataTable(description)
data_table.LoadData(data)
print "Content-type: text/plain"
print
print data_table.ToJSonResponse(columns_order=("name", "salary", "full_time"),
                                order_by="salary")