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
|
您要讀取的字串 對應於 actionId 設定 |
| 互動 | enum(InteractionType)
|
通知 Looker 工作室 互動 |
| 資料 | 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"]
]
}
搭配上述 interactionData 使用 dscc.sendInteraction 等同於
下列 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
這是向 callback註冊
dscc.subscribeToData。以下是這兩個網域之間共用的欄位
《dscc.objectFormat》和《dscc.tableFormat》。
{
fields: object(fieldsByConfigId),
style: object(styleById),
interactions: object(interactionsById),
theme: object(themeStyle),
tables: object(tablesById),
dateRanges: object(dateRangesById)
}
| 欄位 | 類型 | 說明 |
|---|---|---|
| 欄位 | object(fieldsByConfigId)
|
包含 fields 和 他們的 configId |
| 樣式 | object(styleById)
|
包含 樣式物件 已由 configId 編入索引 |
| 互動 | object(interactionsById)
|
包含 互動 物品 |
| 主題 | themeStyle
|
themeStyle 物件 包含主題樣式 關於報表的資訊 |
| 桌子 | object(tablesById)
|
包含 tableObjects |
| dateRanges | object(dateRangesById)
|
包含 dateRanges |
fieldsByConfigId
{
configId: array(field)
}
fieldsByConfigId 物件包含已建立索引的 field 物件陣列
依據「id」
視覺化設定。另有
此物件中會有一個項目，為設定中定義的每個 dataField 使用一個項目。
| 欄位 | 類型 | 說明 |
|---|---|---|
| configId | Array<field> |
與 dataField 相關聯的欄位陣列 |
欄位
{
id: fieldId,
name: string,
description: string,
type: fieldType,
concept: enum(conceptType)
}
field 物件提供使用者所選欄位的相關資訊
「資源」面板
| 欄位 | 類型 | 說明 |
|---|---|---|
| id | string |
Looker Studio 為欄位產生的 ID |
| 名稱 | string |
人類可讀的欄位名稱 |
| 說明 | 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 會提供每列的標題和資料資訊。「預設」
一律會傳回資料，「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。 |
| End | string |
日期範圍的結束日期，格式為 YYYYMMDD。 |
tableFormat 參考資料
tableObject
{
headers: array(object),
rows: array(array)
}
| 欄位 | 類型 | 說明 |
|---|---|---|
| 標題 | Array
|
fields 物件的陣列。這些欄位
物件也會包含 configId 屬性
與設定中的 ID 對應。 |
| 資料列 | Array<Array> |
陣列陣列：每個陣列都是一列資料 |
tableFormat 資料範例
這是搭配 選項使用 dscc.subscribeToData() 時傳回的 data 範例
dscc.tableFormat。
{
"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"
]
}
}
}
objectFormat 參考資料
objectRow
{
configId1: array(string | bool | number),
configId2: array(string | bool | number)
}
| 欄位 | 類型 | 說明 |
|---|---|---|
| configId | 陣列 | 與特定設定 ID 相關聯的值陣列 |
objectFormat 資料範例
這是搭配 選項使用 dscc.subscribeToData() 時傳回的 data 範例
dscc.objectFormat。
{
"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"
]
}
}
}