API 總覽
dscc (Looker Studio 社群元件) 程式庫可協助您建構 Looker Studio 社群元件。您可以在 GitHub 找到原始碼。
dscc 公開三個函式：getWidth()、getHeight() 和 subscribeToData()。
getWidth()
| 名稱 | 參數 | 傳回類型 | 說明 |
|---|---|---|---|
| getWidth() | 無 | number
|
傳回 iframe 的寬度 (以像素為單位) |
使用了 getWidth()
// to get the width of the iframe
var width = dscc.getWidth();
getHeight()
| 名稱 | 參數 | 傳回類型 | 說明 |
|---|---|---|---|
| getHeight() | 無 | int
|
傳回 iframe 的高度 (以像素為單位) |
使用了 getHeight()
// to get the height of the iframe
var height = dscc.getHeight();
sendInteraction()
sendInteraction() 函式會將篩選器資料的訊息傳送至 Looker Studio。
參數：
| 名稱 | 類型 | 說明 |
|---|---|---|
| actionID | string
|
與設定中動作 ID 相對應的字串 |
| 互動 | enum(InteractionType)
|
告知 Looker Studio |
| 資料 | object(InteractionData)
|
提供互動的 必要資料 |
InteractionType
目前唯一有效的 InteractionType 是 FILTER。
| 名稱 | 類型 | 說明 |
|---|---|---|
| dscc.InteractionType.FILTER | 列舉 | 說明 FILTER 互動 |
使用了 sendInteraction
// the actionID can either be hardcoded or parsed from the returned data
var actionId = "interactionConfigId";
// dscc provides enums for the interaction types
var FILTER = dscc.InteractionType.FILTER;
var fieldID = "qt_m9dtntutsb";
var dataValue = "Asia";
// sendInteraction expects data that tells you the concepts and the values of
// those concepts to use in constructing a filter.
var interactionData = {
"concepts": [fieldId],
"values": [[dataValue]]
}
dscc.sendInteraction(actionId, FILTER, interactionData);
interactionData
var interactionData = {
"concepts": array(fieldId),
"values": array(array(dataValue))
}
| 欄位 | 類型 | 說明 |
|---|---|---|
| 概念 | Array |
fieldIds 的陣列 |
| 值 | Array<Array>
|
資料值的巢狀陣列。每個子陣列都應為 concepts 陣列的長度。子陣列中的每個值都會對應到維度值。 |
interactionData 範例：
var interactionData = {
"concepts": ["dim1Id", "dim2Id"],
"values": [
["dim1Val1", "dim2Val1"],
["dim1Val2", "dim2Val2"]
]
}
使用 dscc.sendInteraction 搭配上述 interactionData，等同於下列 SQL 陳述式：
SELECT data WHERE
(dim1 == dim1Val1 AND dim2 == dim2Val1)
OR
(dim1 == dim1Val2 AND dim2 == dim2Val2);
clearInteraction()
clearInteraction() 函式會傳送訊息至 Looker Studio，清除先前由這個視覺化圖表設定的篩選器。
參數：
| 名稱 | 類型 | 說明 |
|---|---|---|
| actionID | string
|
與設定中 actionId 對應的字串 |
| 互動 | enum(InteractionType)
|
告知 Looker Studio |
使用了 clearInteraction()
// the actionID can either be hardcoded or parsed from the returned data
var actionId = "interactionConfigId";
// dscc provides enums for the interaction types
var FILTER = dscc.InteractionType.FILTER;
dscc.clearInteraction(actionId, FILTER);
subscribeToData(callback, options)
subscribeToData() 函式會訂閱 Looker Studio 訊息。
參數：
| 名稱 | 類型 | 說明 |
|---|---|---|
| 回呼(資料) | function
|
這個函式會取用 subscribeToData 傳回的資料。 |
| 選項 | object |
定義所需的資料傳回格式 |
選項物件如下所示：
{
transform: dscc.tableTransform | dscc.objectTransform
}
傳回值：
| 類型 | 說明 |
|---|---|
function |
取消訂閱 callback 的 Looker Studio 更多訊息 |
使用了 subscribeToData()
// define and use a callback
var unsubscribe = dscc.subscribeToData(function(data){
// console.log the returned data
console.log(data);
}, {transform: dscc.tableTransform});
// to unsubscribe
unsubscribe();
data
這是傳遞至 dscc.subscribeToData 所註冊 callback 的物件。以下是 dscc.objectFormat 和 dscc.tableFormat 之間共用的欄位。
{
fields: object(fieldsByConfigId),
style: object(styleById),
interactions: object(interactionsById),
theme: object(themeStyle),
tables: object(tablesById),
dateRanges: object(dateRangesById)
}
| 欄位 | 類型 | 說明 |
|---|---|---|
| 欄位 | object(fieldsByConfigId)
|
包含依 configId 建立索引的欄位的物件 |
| 樣式 | object(styleById)
|
包含樣式物件 (以 configId 建立索引) 的物件 |
| 互動 | object(interactionsById)
|
包含互動物件的物件 |
| 主題 | themeStyle
|
包含報表主題樣式資訊的 themeStyle 物件 |
| 資料表 | object(tablesById)
|
包含 tableObjects 的物件 |
| dateRanges | object(dateRangesById)
|
包含 dateRanges 的物件 |
fieldsByConfigId
{
configId: array(field)
}
fieldsByConfigId 物件包含由視覺化設定中定義的「id」建立索引的「欄位」物件陣列。這個物件中定義的每個 dataField 都有一個項目。
| 欄位 | 類型 | 說明 |
|---|---|---|
| configId | Array<field> |
與 dataField 相關聯的欄位陣列 |
欄位
{
id: fieldId,
name: string,
description: string,
type: fieldType,
concept: enum(conceptType)
}
field 物件會提供使用者在屬性面板中選取的欄位相關資訊。
| 欄位 | 類型 | 說明 |
|---|---|---|
| id | string |
Looker Studio 為欄位產生的 ID |
| 名稱 | string |
使用者可理解的欄位名稱 |
| description | string |
欄位說明 |
| 類型 | enum(fieldType) |
欄位的 semanticType |
| 概念 | enum(conceptType) |
欄位的 conceptType |
styleById
{
configId: styleValue
}
styleById 物件會提供由視覺化設定中定義的「id」建立索引的樣式資訊。
| 欄位 | 類型 | 說明 |
|---|---|---|
| configId | styleValue
|
包含樣式值和設定定義預設樣式值的物件 |
styleValue
{
value: string | object | bool | number,
defaultValue: string | object | bool | number
}
styleValue 物件同時提供使用者選取的樣式值，以及設定中定義的預設值。value 和 defaultValue 的類型取決於樣式元素。
| 欄位 | 類型 | 說明 |
|---|---|---|
| 值 | string OR object OR bool OR
number
|
從使用者選取屬性面板中傳回的樣式元素值 |
| defaultValue | string OR object OR bool OR
number
|
視覺化設定中定義的樣式元素預設值 |
interactionsById
{
}
interactionsById 物件提供由 interactionId
視覺化設定建立索引的互動資料。
| 索引 | 類型 | 說明 |
|---|---|---|
| configId | interaction
|
包含互動相關資料的物件 |
interactionField
{
value: object(interactionValue),
supportedActions: array(InteractionType)
}
interactionField 物件包含設定中定義的 supportedActions 陣列，以及使用者為互動選取的值。
| 欄位 | 類型 | 說明 |
|---|---|---|
| 值 | string OR object OR
bool OR number
|
從使用者選取屬性面板中傳回的樣式元素值 |
| supportedActions | Array<InteractionType>
|
此互動支援的動作，如設定所定義 |
interactionValue
interactionValue 物件會提供使用者選取的互動類型值。如果 data 鍵存在，InteractionData 物件會反映篩選器目前的狀態。如果 data 鍵不存在，表示圖表目前並未設為篩選器。
{
type: enum(InteractionType)
data: object(interactionData) | None
}
| 欄位 | 類型 | 說明 |
|---|---|---|
| 類型 | enum(InteractionType)
|
使用者選擇的 InteractionType |
| 資料 | object(InteractionData)
|
與篩選器目前狀態相關聯的資料。如果目前已清除篩選器，則索引鍵不存在。 |
主題
{
fillColor: {
color: string,
opacity: number
},
fontColor: {
color: string,
opacity: number
},
accentFillColor: {
color: string,
opacity: number
},
accentFontColor: {
color: string,
opacity: number
},
fontFamily: string,
accentFontFamily: string,
increaseColor: {
color: string,
opacity: number
},
decreaseColor: {
color: string,
opacity: number
},
gridColor: {
color: string,
opacity: number
},
seriesColor: [
{
color: string,
opacity: number
}
]
}
themeStyle 物件會將報表主題資訊傳遞至視覺呈現。
| 欄位 | 類型 | 說明 |
|---|---|---|
| fillColor | object
|
{color:
string, opacity: number} 格式的物件 |
| fontColor | object
|
{color:
string, opacity: number} 格式的物件 |
| accentFillColor | object
|
{color:
string, opacity: number} 格式的物件 |
| accentFontColor | object
|
{color:
string, opacity: number} 格式的物件 |
| fontFamily | string |
說明字型系列的字串 |
| accentFontFamily | string
|
說明強調字型系列的字串 |
| increaseColor | object
|
{color:
string, opacity: number} 格式的物件 |
| decreaseColor | object
|
{color:
string, opacity: number} 格式的物件 |
| gridColor | object
|
{color:
string, opacity: number} 格式的物件 |
| seriesColor | Array<object>
|
{color: string, opacity:
number} 格式的物件陣列 |
tablesById
{
"DEFAULT": object(tableObject),
"COMPARISON": object(tableObject) | undefined
}
tableObject 會提供每一列的標題和資料資訊。「DEFAULT」一律會傳回資料，而「COMPARISON」只會在使用者設定包含比較資料列的資料時填入。
tableObject 的格式是 dscc.tableFormat 和 dscc.objectFormat 之間的唯一差異。
| 欄位 | 類型 | 說明 |
|---|---|---|
| "預設" | object(tableObject) OR
Array<objectRow>
|
與使用者新增至圖表的資料相關聯的 tableObject |
| 「比較」 | object(tableObject) OR
Array<objectRow>
|
與日期比較資料相關聯的 tableObject (如適用) |
dateRangesById
{
"DEFAULT": object(dateRange),
"COMPARISON": object(dateRange)
}
dateRangesById 物件提供預設和比較日期範圍的相關資訊。如果沒有日期範圍，物件會留空。只有在使用者個別設定 DEFAULT 和 COMPARISON 的情況下，系統才會填入資料。日期範圍內的資料與 tablesById 中定義的預設和比較資料相關。
| 欄位 | 類型 | 說明 |
|---|---|---|
| "預設" | object(dateRange)
|
與預設日期範圍相關聯的 dateRange (如適用)。 |
| 「比較」 | object(dateRange)
|
與比較日期範圍相關聯的 dateRange (如適用)。 |
dateRange
{
start: string,
end: string
}
dateRange 物件提供預設或比較日期範圍的開始和結束日期的相關資訊。
| 欄位 | 類型 | 說明 |
|---|---|---|
| start | string |
日期範圍的開始日期，格式為 YYYYMMDD。 |
| 結束 | string |
日期範圍的結束日期，格式為 YYYYMMDD。 |
「tableFormat」參考資料
tableObject
{
headers: array(object),
rows: array(array)
}
| 欄位 | 類型 | 說明 |
|---|---|---|
| 標題 | Array
|
fields 物件的陣列。這些欄位物件還有與設定 ID 相對應的 configId 屬性。 |
| 資料列 | Array<Array> |
陣列陣列：每個陣列都是一列資料 |
tableFormat 範例資料
以下是搭配使用 dscc.subscribeToData() 與 dscc.tableFormat 選項傳回的 data 範例。
{
"tables": {
"DEFAULT": {
"headers": [{
"id": "qt_ky8sltutsb",
"name": "dimension",
"type": "TEXT",
"concept": "DIMENSION",
"configId": "configId1"
}, {
"id": "qt_b5bvmtutsb",
"name": "second dim",
"type": "TEXT",
"concept": "DIMENSION"
"configId": "configId1"
}, {
"id": "qt_m9dtntutsb",
"name": "metric",
"type": "NUMBER",
"concept": "METRIC",
"configId": "configId2"
}],
"rows": [
["Week 4", "lm", 55]
]
},
"COMPARISON": {
"headers": [{
"id": "qt_ky8sltutsb",
"name": "dimension",
"type": "TEXT",
"concept": "DIMENSION",
"configId": "configId1"
}, {
"id": "qt_b5bvmtutsb",
"name": "second dim",
"type": "TEXT",
"concept": "DIMENSION"
"configId": "configId1"
}, {
"id": "qt_m9dtntutsb",
"name": "metric",
"type": "NUMBER",
"concept": "METRIC",
"configId": "configId2"
}],
"rows": [
["Week 5", "no", 123]
]
}
},
"fields": {
"configId1": [
{
"id": "qt_ky8sltutsb",
"name": "week",
"type": "TEXT",
"concept": "DIMENSION"
},
{
"id": "qt_b5bvmtutsb",
"name": "textId",
"type": "TEXT",
"concept": "DIMENSION"
}
],
"configId2": [
{
"id": "qt_m9dtntutsb",
"name": "orders",
"type": "NUMBER",
"concept": "METRIC"
}
]
},
"style": {
"nodeColor": {
"value": {
"color": "#000000"
}
}
},
"theme": {},
"dateRanges": {
"DEFAULT": {
"start": "20210501",
"end": "20210531"
},
"COMPARISON": {
"start": "20200501",
"end": "20200531"
}
},
"interactions": {
"onClick": {
"value": {
"type": "FILTER",
"data": {
"concepts": [
"qt_h6oibrb6wb",
"qt_i6oibrb6wb"
],
"values": [
[
"Afternoon",
"Sunday"
],
[
"Afternoon",
"Thursday"
],
[
"Morning",
"Tuesday"
]
]
}
},
"supportedActions": [
"FILTER"
]
}
}
}
物件格式參考資料
objectRow
{
configId1: array(string | bool | number),
configId2: array(string | bool | number)
}
| 欄位 | 類型 | 說明 |
|---|---|---|
| configId | 陣列 | 與特定設定 ID 相關聯的值陣列 |
objectFormat 資料範例
以下是搭配使用 dscc.subscribeToData() 與 dscc.objectFormat 選項傳回的 data 範例。
{
"tables": {
"COMPARISON": [
{
"configId1": ["Week 5", "cd"],
"configId2": [123]
}
],
"DEFAULT": [
{
"configId1": ["Week 1", "ab"],
"configId2": [24]
}
]
},
"fields": {
"configId1": [
{
"id": "qt_h6oibrb6wb",
"name": "time of day",
"type": "TEXT",
"concept": "DIMENSION"
},
{
"id": "qt_i6oibrb6wb",
"name": "day",
"type": "TEXT",
"concept": "DIMENSION"
}
],
"configId2": [
{
"id": "qt_m9dtntutsb",
"name": "metric",
"type": "NUMBER",
"concept": "METRIC"
}
]
},
"style": {
"nodeColor": {
"value": {
"color": "#000000"
}
}
},
"theme": {},
"dateRanges": {
"DEFAULT": {
"start": "20210501",
"end": "20210531"
},
"COMPARISON": {
"start": "20200501",
"end": "20200531"
}
},
"interactions": {
"onClick": {
"value": {
"type": "FILTER",
"data": {
"concepts": [
"qt_h6oibrb6wb",
"qt_i6oibrb6wb"
],
"values": [
[
"Afternoon",
"Sunday"
],
[
"Afternoon",
"Thursday"
],
[
"Morning",
"Tuesday"
]
]
}
},
"supportedActions": [
"FILTER"
]
}
}
}