Referência da biblioteca do componente da comunidade do Data Studio (dscc)

Visão geral da API

O dscc (componente da comunidade do Data Studio) é uma biblioteca para ajudar na criação de componentes da comunidade para o Data Studio. O código-fonte fica no GitHub.

dscc retorna três funções: getWidth(), getHeight() e subscribeToData().

getWidth()

Nome Parâmetros Tipo de retorno Descrição
getWidth() Nenhum number Retorna a largura do iframe em pixels.

Uso do getWidth()

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

getHeight()

Nome Parâmetros Tipo de retorno Descrição
getHeight() Nenhum int Retorna a altura do iframe em pixels.

Uso do getHeight()

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

sendInteraction()

A função sendInteraction() envia uma mensagem para o Data Studio com os dados de um filtro.

Parâmetros:

Nome Tipo Descrição
actionID string String que corresponde ao actionId na configuração.
interaction enum(InteractionType) Informa o Data Studio sobre a interação.
data object(InteractionData) Fornece os dados necessários para uma interação.

InteractionType

No momento, o único InteractionType válido é FILTER.

Nome Tipo Descrição
dscc.InteractionType.FILTER Enum Descreve a interação FILTER.

Uso do 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))
    }
    
Campo Tipo Descrição
concepts Array Matriz de fieldIds
values Array<Array> Matriz aninhada de valores de dados. Cada submatriz precisa ter o tamanho da matriz de concepts. Todos os valores na submatriz correspondem a um valor de dimensão.

Exemplo de interactionData:

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

Usar dscc.sendInteraction com o interactionData acima é equivalente à seguinte instrução SQL:

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

clearInteraction()

A função clearInteraction() envia uma mensagem ao Data Studio para limpar um filtro definido anteriormente por essa visualização.

Parâmetros:

Nome Tipo Descrição
actionID string String que corresponde ao actionId na configuração.
interaction enum(InteractionType) Informa o Data Studio sobre a interação.

Uso do 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)

A função subscribeToData() se inscreve nas mensagens do Data Studio.

Parâmetros:

Nome Tipo Descrição
callback(data) function Uma função que usa os dados retornados por subscribeToData.
options object Define o formato de retorno de dados desejado.

O objeto "options" tem esta aparência:

{
      transform: dscc.tableTransform | dscc.objectTransform
    }
    

Valor de retorno:

Tipo Descrição
function Cancela a inscrição em callback de outras mensagens do Data Studio

Uso do 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

É o objeto enviado para callback registrado com dscc.subscribeToData. Veja a seguir os campos que são compartilhados entre dscc.objectFormat e dscc.tableFormat.

{
      fields: object(fieldsByConfigId),
      style: object(styleById),
      interactions: object(interactionsById),
      theme: object(themeStyle),
      tables: object(tablesById)
    }
    
Campo Tipo Descrição
fields object(fieldsByConfigId) Objeto que contém campos indexados pelo configId.
style object(styleById) Objeto que contém objetos de estilo indexados pelo configId.
interactions object(interactionsById) Objeto que contém objetos de interação.
theme themeStyle Objeto themeStyle que contém informações de estilo do tema para o relatório.
tables object(tablesById) Objeto que contém tableObjects.

fieldsByConfigId

{
       configId: array(field)
    }
    

O objeto fieldsByConfigId contém matrizes de objetos de campo indexados pelo "id" definido na configuração de visualização . Há uma entrada nesse objeto para cada dataField determinado na configuração.

Campo Tipo Descrição
configId Array<field> Uma matriz de campos associados ao dataField.

field

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

O objeto field fornece informações sobre o campo que o usuário seleciona no painel de propriedades.

Campo Tipo Descrição
id string Código gerado pelo Data Studio para o campo.
name string Nome legível do campo.
description string Descrição do campo.
type enum(fieldType) Valor semanticType do campo.
concept enum(conceptType) Valor conceptType do campo.

styleById

{
       configId: styleValue
    }
    

O objeto styleById fornece informações de estilo indexadas pelo "id" definido na configuração de visualização .

Campo Tipo Descrição
configId styleValue Objeto que contém o valor do estilo comum e o valor do estilo padrão definido pela configuração.

styleValue

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

O objeto styleValue fornece o valor de estilo selecionado pelo usuário e o valor padrão definido na configuração. O tipo de value e defaultValue depende do elemento de estilo.

Campo Tipo Descrição
value string OR object OR bool OR number Valor do elemento de estilo retornado da seleção do usuário no painel de propriedades.
defaultValue string OR object OR bool OR number Valor padrão do elemento de estilo definido na configuração da visualização.

interactionsById

{

    }
    

O objeto interactionsById fornece dados de interação indexados pela configuração de visualização do interactionId.

Índice Tipo Descrição
configId interaction Objeto que contém dados associados a uma interação.

interactionField

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

O objeto interactionField contém a matriz de supportedActions definida na configuração, bem como os valores selecionados pelo usuário para a interação.

Campo Tipo Descrição
value string OR object OR bool OR number Valor do elemento de estilo retornado da seleção do usuário no painel de propriedades.
supportedActions Array<InteractionType> Ações compatíveis com essa interação, conforme definidas na configuração.

interactionValue

O objeto interactionValue fornece valores selecionados pelo usuário para o tipo de interação. Se a chave data existir, o objeto InteractionData aplicará o estado atual do filtro. Se não houver uma chave data, a visualização não está configurada como um filtro.

{
      type: enum(InteractionType)
      data: object(interactionData) | None
    }
    
Campo Tipo Descrição
type enum(InteractionType) InteractionType selecionado pelo usuário.
data object(InteractionData) Os Dados associados ao estado atual do filtro. Essa chave não estará presente se o filtro estiver vazio.

theme

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

O objeto themeStyle transmite as informações do tema de relatório para a visualização.

Campo Tipo Descrição
fillColor object Objeto com o formato {color: string, opacity: number}.
fontColor object Objeto com o formato {color: string, opacity: number}.
accentFillColor object Objeto com o formato {color: string, opacity: number}.
accentFontColor object Objeto com o formato {color: string, opacity: number}.
fontFamily string String que descreve a família de fontes.
accentFontFamily string String que descreve a família de fontes de destaque.
increaseColor object Objeto com o formato {color: string, opacity: number}.
decreaseColor object Objeto com o formato {color: string, opacity: number}.
gridColor object Objeto com o formato {color: string, opacity: number}.
seriesColor Array<object> Matriz de objetos do formato {color: string, opacity: number}.

tablesById

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

O objeto tableObject fornece informações de cabeçalho e dados de cada linha. "DEFAULT" sempre retornará dados, e "COMPARISON" será preenchido apenas se o usuário configurar os dados com linhas de comparação.

O formato do tableObject é a única diferença entre dscc.tableFormat e dscc.objectFormat.

Campo Tipo Descrição
DEFAULT object(tableObject) OR Array<objectRow> tableObject associado aos dados que um usuário adiciona a uma visualização.
COMPARISON object(tableObject) OR Array<objectRow> tableObject associado aos dados de comparação de datas, se aplicável.

Referência do tableFormat

tableObject

{
      headers: array(object),
      rows: array(array)
    }
    
Campo Tipo Descrição
headers Array Matriz de objetos de campos. Esses objetos de campo também têm uma propriedade configId que corresponde aos códigos da configuração.
rows Array<Array> Matriz de matrizes: cada matriz é uma linha de dados.

Dados de tableFormat de amostra

Este é um exemplo de data retornado usando dscc.subscribeToData() com a opção 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": {},
      "interactions": {
        "onClick": {
          "value": {
            "type": "FILTER",
            "data": {
              "concepts": [
                "qt_h6oibrb6wb",
                "qt_i6oibrb6wb"
              ],
              "values": [
                [
                  "Afternoon",
                  "Sunday"
                ],
                [
                  "Afternoon",
                  "Thursday"
                ],
                [
                  "Morning",
                  "Tuesday"
                ]
              ]
            }
          },
          "supportedActions": [
            "FILTER"
          ]
        }
      }
    }
    

Referência de objectFormat

objectRow

{
      configId1: array(string | bool | number),
      configId2: array(string | bool | number)
    }
    
Campo Tipo Descrição
configId Matriz Matriz de valores associados a um código de configuração específico.

Dados de objectFormat de amostra

Este é um exemplo de data retornado usando dscc.subscribeToData() com a opção 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": {},
      "interactions": {
        "onClick": {
          "value": {
            "type": "FILTER",
            "data": {
              "concepts": [
                "qt_h6oibrb6wb",
                "qt_i6oibrb6wb"
              ],
              "values": [
                [
                  "Afternoon",
                  "Sunday"
                ],
                [
                  "Afternoon",
                  "Thursday"
                ],
                [
                  "Morning",
                  "Tuesday"
                ]
              ]
            }
          },
          "supportedActions": [
            "FILTER"
          ]
        }
      }
    }