Tài liệu tham khảo về thư viện Thành phần cộng đồng Looker Studio (dscc)

Tổng quan về API

dscc (Thành phần cộng đồng Looker Studio) là một thư viện giúp xây dựng các thành phần cộng đồng cho Looker Studio. Bạn có thể tìm thấy mã nguồn trên GitHub.

dscc cho thấy 3 hàm: getWidth(), getHeight() và subscribeToData().

getWidth()

Tên Các tham số Loại dữ liệu trả về Nội dung mô tả
getWidth() Không có number Trả về chiều rộng của iframe, tính bằng pixel

Sử dụng getWidth()

// to get the width of the iframe
var width = dscc.getWidth();

getHeight()

Tên Các tham số Loại dữ liệu trả về Nội dung mô tả
getHeight() Không có int Trả về chiều cao của iframe, tính bằng pixel

Sử dụng getHeight()

// to get the height of the iframe
var height = dscc.getHeight();

sendInteraction()

Hàm sendInteraction() gửi thông báo đến Looker Studio kèm theo dữ liệu cho một bộ lọc.

Các thông số:

Tên Loại Nội dung mô tả
actionID string Chuỗi tương ứng với actionId trong cấu hình
hành động tương tác enum(InteractionType) Cho Looker Studio biết về hoạt động tương tác
data object(InteractionData) Cung cấp dữ liệu bắt buộc cho một lượt tương tác

InteractionType

Hiện tại, InteractionType hợp lệ duy nhất là FILTER.

Tên Loại Nội dung mô tả
dscc.InteractionType.FILTER Liệt kê Mô tả tương tác FILTER

Sử dụng 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))
}
Trường Loại Nội dung mô tả
khái niệm Array Mảng fieldIds
giá trị Array<Array> Mảng giá trị dữ liệu lồng nhau. Mỗi mảng con phải bằng độ dài của mảng concepts. Mỗi giá trị trong mảng con tương ứng với một giá trị phương diện.

Mẫu interactionData:

var interactionData = {
  "concepts": ["dim1Id", "dim2Id"],
  "values": [
    ["dim1Val1", "dim2Val1"],
    ["dim1Val2", "dim2Val2"]
    ]
}

Việc sử dụng dscc.sendInteraction với interactionData ở trên tương đương với câu lệnh SQL sau:

SELECT data WHERE
  (dim1 == dim1Val1 AND dim2 == dim2Val1)
  OR
  (dim1 == dim1Val2 AND dim2 == dim2Val2);

clearInteraction()

Hàm clearInteraction() gửi thông báo đến Looker Studio để xoá bộ lọc đã đặt trước đó theo hình ảnh trực quan này.

Các thông số:

Tên Loại Nội dung mô tả
actionID string Chuỗi tương ứng với actionId trong cấu hình
hành động tương tác enum(InteractionType) Cho Looker Studio biết về hoạt động tương tác

Sử dụng 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)

Hàm subscribeToData() đăng ký nhận thông báo từ Looker Studio.

Các thông số:

Tên Loại Nội dung mô tả
callback(dữ liệu) function Một hàm nhận dữ liệu do subscribeToData trả về.
tùy chọn object Xác định định dạng dữ liệu trả về mong muốn

Đối tượng tuỳ chọn sẽ có dạng như sau:

{
  transform: dscc.tableTransform | dscc.objectTransform
}

Giá trị trả về:

Loại Nội dung mô tả
function Huỷ đăng ký callback nhận thông báo khác từ Looker Studio

Sử dụng 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

Đây là đối tượng được truyền đến callback đã đăng ký bằng dscc.subscribeToData. Sau đây là các trường được chia sẻ giữa dscc.objectFormat và dscc.tableFormat.

{
  fields: object(fieldsByConfigId),
  style: object(styleById),
  interactions: object(interactionsById),
  theme: object(themeStyle),
  tables: object(tablesById),
  dateRanges: object(dateRangesById)
}
Trường Loại Nội dung mô tả
fields object(fieldsByConfigId) Một đối tượng chứa các trường được lập chỉ mục bởi configId
kiểu object(styleById) Một đối tượng chứa đối tượng kiểu được lập chỉ mục theo configId
hoạt động tương tác object(interactionsById) Một đối tượng chứa các đối tượng tương tác
chủ đề themeStyle Đối tượng themeStyle chứa thông tin định kiểu giao diện cho báo cáo
bàn object(tablesById) Một đối tượng chứa tableObjects
dateRanges object(dateRangesById) Đối tượng chứa dateRanges

fieldsByConfigId

{
   configId: array(field)
}

Đối tượng fieldsByConfigId chứa các mảng đối tượng trường được lập chỉ mục bởi "id" (mã nhận dạng) được xác định trong cấu hình trực quan hoá. Có một mục nhập trong đối tượng này cho mỗi dataField được xác định trong cấu hình.

Trường Loại Nội dung mô tả
configId Array<field> Mảng các trường được liên kết với dataField

trường

{
  id: fieldId,
  name: string,
  description: string,
  type: fieldType,
  concept: enum(conceptType)
}

Đối tượng field cung cấp thông tin về trường mà người dùng chọn trong bảng thuộc tính.

Trường Loại Nội dung mô tả
id string Mã nhận dạng do Looker Studio tạo cho trường này
tên string Tên trường mà con người có thể đọc được
description string Nội dung mô tả về trường
loại enum(fieldType) semanticType của trường
khái niệm enum(conceptType) conceptType của trường

styleById

{
   configId: styleValue
}

Đối tượng styleById cung cấp thông tin kiểu được lập chỉ mục theo "id" được xác định trong cấu hình hình ảnh.

Trường Loại Nội dung mô tả
configId styleValue Một đối tượng chứa giá trị kiểu và giá trị kiểu mặc định do cấu hình xác định

styleValue

{
  value: string | object | bool | number,
  defaultValue: string | object | bool | number
}

Đối tượng styleValue cung cấp cả giá trị kiểu do người dùng chọn và giá trị mặc định được xác định trong cấu hình. Loại value và defaultValue phụ thuộc vào phần tử kiểu.

Trường Loại Nội dung mô tả
value string OR object OR bool OR number Giá trị của phần tử kiểu được trả về từ lựa chọn của người dùng trong bảng thuộc tính
defaultValue string OR object OR bool OR number Giá trị mặc định của phần tử kiểu được xác định trong cấu hình hình ảnh trực quan

interactionsById

{

}

Đối tượng interactionsById cung cấp dữ liệu về lượt tương tác được lập chỉ mục bởi cấu hình trực quan hoá interactionId.

Chỉ mục Loại Nội dung mô tả
configId interaction Đối tượng chứa dữ liệu liên kết với một lượt tương tác

interactionField

{
  value: object(interactionValue),
  supportedActions: array(InteractionType)
}

Đối tượng interactionField chứa mảng supportedActions được xác định trong cấu hình, cũng như các giá trị do người dùng chọn cho tương tác đó.

Trường Loại Nội dung mô tả
value string OR object OR bool OR number Giá trị của phần tử kiểu được trả về từ lựa chọn của người dùng trong bảng thuộc tính
supportedActions Array<InteractionType> Các thao tác được tương tác này hỗ trợ, như xác định trong phần cấu hình

interactionValue

Đối tượng interactionValue cung cấp các giá trị do người dùng chọn cho loại tương tác. Nếu khoá data tồn tại, thì đối tượng InteractionData sẽ phản ánh trạng thái hiện tại của bộ lọc. Nếu khoá data không tồn tại, thì hình ảnh trực quan hiện không được định cấu hình làm bộ lọc.

{
  type: enum(InteractionType)
  data: object(interactionData) | None
}
Trường Loại Nội dung mô tả
loại enum(InteractionType) InteractionType do người dùng chọn
data object(InteractionData) Dữ liệu liên kết với trạng thái hiện tại của bộ lọc. Khoá này không tồn tại nếu bộ lọc hiện đã bị xoá.

chủ đề

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

Đối tượng themeStyle truyền thông tin giao diện báo cáo đến hình ảnh trực quan.

Trường Loại Nội dung mô tả
fillColor object Đối tượng có định dạng {color: string, opacity: number}
fontColor object Đối tượng có định dạng {color: string, opacity: number}
accentFillColor object Đối tượng có định dạng {color: string, opacity: number}
accentFontColor object Đối tượng có định dạng {color: string, opacity: number}
fontFamily string Một chuỗi mô tả bộ phông chữ
accentFontFamily string Một chuỗi mô tả họ phông chữ nhấn
increaseColor object Đối tượng có định dạng {color: string, opacity: number}
decreaseColor object Đối tượng có định dạng {color: string, opacity: number}
gridColor object Đối tượng có định dạng {color: string, opacity: number}
seriesColor Array<object> Một mảng các đối tượng có định dạng{color: string, opacity: number}

tablesById

{
  "DEFAULT": object(tableObject),
  "COMPARISON": object(tableObject) | undefined
}

tableObject cung cấp thông tin về tiêu đề và dữ liệu cho mỗi hàng. "DEFAULT" sẽ luôn trả về dữ liệu, còn "COMPARISON" (SOẠN) sẽ chỉ được điền nếu người dùng định cấu hình dữ liệu với các hàng so sánh.

Định dạng của tableObject là sự khác biệt duy nhất giữa dscc.tableFormat và dscc.objectFormat.

Trường Loại Nội dung mô tả
"DEFAULT" object(tableObject) OR Array<objectRow> tableObject được liên kết với dữ liệu mà người dùng thêm vào hình ảnh trực quan
"SO SÁNH" object(tableObject) OR Array<objectRow> tableObject được liên kết với dữ liệu so sánh ngày, nếu có

dateRangesById

{
  "DEFAULT": object(dateRange),
  "COMPARISON": object(dateRange)
}

Đối tượng dateRangesById cung cấp thông tin về phạm vi ngày mặc định và so sánh. Nếu không có phạm vi ngày, đối tượng sẽ trống. DEFAULT và COMPARISON sẽ chỉ được điền nếu người dùng định cấu hình phạm vi ngày tương ứng. Dữ liệu trong phạm vi ngày có liên quan đến dữ liệu mặc định và dữ liệu so sánh như xác định trong tablesById.

Trường Loại Nội dung mô tả
"DEFAULT" object(dateRange) dateRange được liên kết với phạm vi ngày mặc định, nếu có.
"SO SÁNH" object(dateRange) dateRange được liên kết với phạm vi ngày so sánh, nếu có.

dateRange

{
  start: string,
  end: string
}

Đối tượng dateRange cung cấp thông tin về ngày bắt đầu và ngày kết thúc của một phạm vi ngày mặc định hoặc so sánh.

Trường Loại Nội dung mô tả
bắt đầu string Ngày bắt đầu trong phạm vi ngày ở định dạng YYYYMMDD.
end string Ngày kết thúc của phạm vi ngày ở định dạng YYYYMMDD.

Tham chiếu tableFormat

tableObject

{
  headers: array(object),
  rows: array(array)
}
Trường Loại Nội dung mô tả
headers Array Một mảng các đối tượng trường. Ngoài ra, các đối tượng trường này còn có một thuộc tính configId tương ứng với mã nhận dạng trong cấu hình.
hàng Array<Array> Một mảng mảng: mỗi mảng là một hàng dữ liệu

Dữ liệu tableFormat mẫu

Đây là mẫu data được trả về bằng cách sử dụng dscc.subscribeToData() với tuỳ chọn 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"
      ]
    }
  }
}

Tham chiếu objectFormat

objectRow

{
  configId1: array(string | bool | number),
  configId2: array(string | bool | number)
}
Trường Loại Nội dung mô tả
configId mảng mảng giá trị được liên kết với một mã cấu hình cụ thể

Dữ liệu objectFormat mẫu

Đây là mẫu data được trả về bằng cách sử dụng dscc.subscribeToData() với tuỳ chọn 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"
      ]
    }
  }
}