Справочник по библиотеке компонентов сообщества Looker Studio (dscc)

Обзор 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 сообщение с данными для фильтра.

Параметры:

Имя Тип Описание
идентификатор действия string Строка, соответствующая actionId в конфигурации.
взаимодействие 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 сообщение об очистке фильтра, ранее установленного этой визуализацией.

Параметры:

Имя Тип Описание
идентификатор действия 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) Объект, содержащий поля , индексированные по их configId.
стиль object(styleById) Объект, содержащий объекты стиля , индексированные по их configId.
взаимодействия object(interactionsById) Объект, содержащий объекты взаимодействия.
тема themeStyle Объект themeStyle , содержащий информацию о стиле темы для отчета.
столы object(tablesById) Объект, содержащий tableObjects
ДатаДиапазоны object(dateRangesById) Объект, содержащий dateRanges

поля поконфигид

{
   configId: array(field)
}

Объект fieldsByConfigId содержит массивы объектов полей , индексированных по идентификатору, определенному в конфигурации визуализации . В этом объекте есть одна запись для каждого dataField , определенного в конфигурации.

Поле Тип Описание
идентификатор конфигурации Array<field> Массив полей, связанных с dataField.

поле

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

Объект field предоставляет информацию о поле, которое пользователь выбирает на панели свойств.

Поле Тип Описание
идентификатор string Looker Studio сгенерировала идентификатор для поля.
имя string Удобочитаемое имя поля
описание string Описание поля
тип enum(fieldType) SemanticType поля
концепция enum(conceptType) КонцепцияТип поля

styleById

{
   configId: styleValue
}

Объект styleById предоставляет информацию о стиле, индексированную по «id», определенному в конфигурации визуализации .

Поле Тип Описание
идентификатор конфигурации styleValue Объект, содержащий значение стиля и значение стиля по умолчанию, определенное в конфигурации.

стильзначение

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

Объект styleValue предоставляет как значение стиля, выбранное пользователем, так и значение по умолчанию, определенное в конфигурации. Тип value и defaultValue зависят от элемента стиля.

Поле Тип Описание
ценить string OR object OR bool OR number Значение элемента стиля, возвращаемое пользователем при выборе на панели свойств.
значение по умолчанию string OR object OR bool OR number Значение по умолчанию для элемента стиля, определенного в конфигурации визуализации.

взаимодействия по идентификатору

{

}

Объект interactionsById предоставляет данные взаимодействия, индексированные конфигурацией визуализации interactionId .

Индекс Тип Описание
идентификатор конфигурации interaction Объект, содержащий данные, связанные с взаимодействием.

Поле взаимодействия

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

Объект interactionField содержит массив поддерживаемых действий, определенных в конфигурации, а также выбранные пользователем значения для взаимодействия.

Поле Тип Описание
ценить string OR object OR bool OR number Значение элемента стиля, возвращаемое пользователем при выборе на панели свойств.
поддерживаетсяДействия Array<InteractionType> Действия, поддерживаемые этим взаимодействием, как определено в конфигурации.

значение взаимодействия

Объект interactionValue предоставляет выбранные пользователем значения для типа взаимодействия. Если ключ data существует, объект InteractionData отражает текущее состояние фильтра. Если ключ data не существует, визуализация в настоящее время не настроена как фильтр.

{
  type: enum(InteractionType)
  data: object(interactionData) | None
}
Поле Тип Описание
тип enum(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 передает информацию о теме отчета в визуализацию.

Поле Тип Описание
Цвет заливки object Объект формата {color: string, opacity: number}
Цвет шрифта object Объект формата {color: string, opacity: number}
акцентЗаливкаЦвет object Объект формата {color: string, opacity: number}
акцентШрифтЦвет object Объект формата {color: string, opacity: number}
семейство шрифтов string Строка, описывающая семейство шрифтов.
AccentFontFamily string Строка, описывающая семейство акцентных шрифтов.
увеличитьЦвет object Объект формата {color: string, opacity: number}
уменьшениеЦвет object Объект формата {color: string, opacity: number}
сеткаЦвет object Объект формата {color: string, opacity: number}
серияЦвет Array<object> Массив объектов формата {color: string, opacity: number}

таблицы по идентификатору

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

tableObject предоставляет информацию о заголовках и данных для каждой строки. «ПО УМОЛЧАНИЮ» всегда будет возвращать данные, а «СРАВНЕНИЕ» будет заполнено только в том случае, если пользователь настраивает данные со строками сравнения.

Формат 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 будут заполнены только в том случае, если соответствующие диапазоны дат настроены пользователем. Данные в диапазонах дат связаны с данными по умолчанию и данными сравнения, как определено в tableById .

Поле Тип Описание
"ПО УМОЛЧАНИЮ" object(dateRange) dateRange , связанный с диапазоном дат по умолчанию, если применимо.
"СРАВНЕНИЕ" object(dateRange) dateRange , связанный с диапазоном дат сравнения, если применимо.

диапазон дат

{
  start: string,
  end: string
}

Объект dateRange предоставляет информацию о датах начала и окончания диапазона дат по умолчанию или диапазона дат сравнения.

Поле Тип Описание
начинать string Дата начала диапазона дат в формате ГГГГММДД.
конец string Конечная дата диапазона дат в формате ГГГГММДД.

Справочник tableFormat

таблицаОбъект

{
  headers: array(object),
  rows: array(array)
}
Поле Тип Описание
заголовки Array Массив объектов полей . Эти объекты полей дополнительно имеют свойство configId , соответствующее идентификаторам из конфигурации.
ряды Array<Array> Массив массивов: каждый массив представляет собой строку данных.

Пример данных tableFormat

Это пример data , возвращаемых с помощью dscc.subscribeToData() с опцией 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"
      ]
    }
  }
}

Ссылка на формат объекта

объектстрока

{
  configId1: array(string | bool | number),
  configId2: array(string | bool | number)
}
Поле Тип Описание
идентификатор конфигурации множество массив значений, связанных с определенным идентификатором конфигурации

Пример данных формата объекта

Это пример data , возвращаемых с помощью dscc.subscribeToData() с опцией 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"
      ]
    }
  }
}