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"
]
}
}
}