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 bạn xây dựng thành phần cộng đồng cho Looker Studio. 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 Tham số Loại trả về Mô tả
getWidth() Không có number Trả về chiều rộng của iframe, theo định dạng pixel

Sử dụng getWidth()

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

getHeight()

Tên Tham số Loại trả về 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 kèm theo dữ liệu đến Looker Studio cho bộ lọc.

Các thông số:

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

InteractionType

Hiện tại, chỉ có InteractionType hợp lệ là FILTER.

Tên Loại Mô tả
dscc.InteractionType.FILTER Enum 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 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 là độ dài của mảng concepts. Mỗi giá trị trong mảng con tương ứng với một giá trị thứ nguyê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á một bộ lọc đã đặt trước đó theo hình ảnh trực quan này.

Các thông số:

Tên Loại 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ề hành độ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 tin nhắn từ Looker Studio.

Các thông số:

Tên Loại Mô tả
lệnh gọi lại(dữ liệu) function Hàm nhận dữ liệu được trả về bởi subscribeToData.
tùy chọn object Xác định định dạng trả về dữ liệu mong muốn

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

{
  transform: dscc.tableTransform | dscc.objectTransform
}

Giá trị trả về:

Loại Mô tả
function Huỷ đăng ký callback nhận các tin nhắn 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 Mô tả
fields object(fieldsByConfigId) Đối tượng chứa trường được lập chỉ mục bởi mã cấu hình của họ
kiểu object(styleById) Đối tượng chứa đối tượng định kiểu được lập chỉ mục theo configId của họ
hoạt động tương tác object(interactionsById) Đối tượng chứa lượt tương tác đối tượng
chủ đề themeStyle Đối tượng themeStyle có chứa kiểu giao diện thông tin cho báo cáo
bảng object(tablesById) Đố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 gồm các đối tượng trường được lập chỉ mục theo "id" đượ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 Mô tả
configId Array<field> Một mảng trường được liên kết với trường dữ liệu

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 bảng điều khiển thuộc tính.

Trường Loại Mô tả
id string Mã 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 (Loại ngữ nghĩa) 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 mà "id" lập chỉ mục được xác định trong cấu hình hiển thị.

Trường Loại Mô tả
configId styleValue Đố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 lẫn giá trị mặc định được xác định trong cấu hình. Loại value và defaultValue phụ thuộc vào yếu tố kiểu.

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

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 interactionId cấu hình trực quan hoá.

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

interactionField

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

Đối tượng interactionField chứa một mảng hành động được hỗ trợ đượ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 Mô tả
value string OR object OR bool OR number Giá trị của phần tử kiểu trả về từ lựa chọn của người dùng trong bảng điều khiển thuộc tính
supportedActions Array<InteractionType> Các thao tác được hỗ trợ tương tác như được xác định trong cấu hình

interactionValue

Đối tượng interactionValue cung cấp các giá trị do người dùng chọn cho tương tác loại. Nếu khoá data tồn tại, đố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, 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 Mô tả
loại enum(InteractionType) Người dùng chọn InteractionType
dữ liệu object(InteractionData) Dữ liệu được 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 về giao diện báo cáo sang hình ảnh trực quan.

Trường Loại Mô tả
fillColor object Một đối tượng có định dạng {color: string, opacity: number}
fontColor object Một đối tượng có định dạng {color: string, opacity: number}
accentFillColor object Một đối tượng có định dạng {color: string, opacity: number}
accentFontColor object Một đối tượng có định dạng {color: string, opacity: number}
fontFamily string Chuỗi mô tả bộ phông chữ
accentFontFamily string Một chuỗi mô tả phông chữ trọng âm gia đình
increaseColor object Một đối tượng có định dạng {color: string, opacity: number}
decreaseColor object Một đối tượng có định dạng {color: string, opacity: number}
gridColor object Một đối tượng có định dạng {color: string, opacity: number}
seriesColor Array<object> Một mảng đối tượng của định dạng{color: string, opacity: number}

tablesById

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

tableObject cung cấp thông tin về dữ liệu và tiêu đề cho mỗi hàng. "MẶC ĐỊNH" sẽ luôn trả về dữ liệu và "COMPARISON" sẽ chỉ được điền nếu người dùng định cấu hình dữ liệu bằng các hàng so sánh.

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

Trường Loại Mô tả
"MẶC ĐỊNH" object(tableObject) OR Array<objectRow> tableObject được liên kết với dữ liệu mà một người dùng thêm vào trực quan hoá
"SO SÁNH" object(tableObject) OR Array<objectRow> tableObject được liên kết với dữ liệu so sánh theo ngày, nếu thích hợp

dateRangesById

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

Đối tượng dateRangesById cung cấp thông tin về giá trị mặc định và thông tin so sánh phạm vi ngày. Nếu không có phạm vi ngày, đối tượng sẽ là trống. DEFAULT và COMPARISON sẽ chỉ được điền nếu là ngày tương ứng các dải ô do người dùng định cấu hình. Dữ liệu trong phạm vi ngày 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 Mô tả
"MẶC ĐỊNH" 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 một 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 Mô tả
bắt đầu string Ngày bắt đầu của phạm vi ngày theo định dạng YYYYMMDD.
end string Ngày kết thúc của phạm vi ngày theo định dạng YYYYMMDD.

Tham chiếu tableFormat

tableObject

{
  headers: array(object),
  rows: array(array)
}
Trường Loại Mô tả
tiêu đề Array Một mảng các đối tượng trường. Các trường này Các đối tượng sẽ có thêm 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 mẫu của tableFormat

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

Thông tin tham chiếu objectFormat

objectRow

{
  configId1: array(string | bool | number),
  configId2: array(string | bool | number)
}
Trường Loại 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 đối tượng 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"
      ]
    }
  }
}