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

Visão geral da API

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

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 Looker Studio com os dados. de um filtro.

Parâmetros:

Nome Tipo Descrição
actionID string String que corresponde ao actionId na configuração.
interação enum(InteractionType) Informa o Looker Sobre o Studio a interação
dados 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
conceitos Array Matriz de fieldIds
valores 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 Looker Studio para limpar filtro definido anteriormente por esta visualização.

Parâmetros:

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

Como usar o 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() assina as mensagens do Looker 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 Looker Studio

Como usar o 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),
  dateRanges: object(dateRangesById)
}
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.
dateRanges object(dateRangesById) Um objeto que contém dateRanges

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 neste objeto para cada dataField definido 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 O ID gerado pelo Looker Studio para o campo
nome 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) O 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.

tema

{
  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.

dateRangesById

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

O objeto dateRangesById fornece informações sobre padrões e comparações períodos. Se não houver períodos, o objeto será vazio. DEFAULT e COMPARISON só serão preenchidos se a respectiva data são configurados pelo usuário. Os dados nos períodos estão relacionados os dados padrão e de comparação, conforme definido em tablesById.

Campo Tipo Descrição
DEFAULT object(dateRange) O dateRange associado ao período padrão, se aplicável.
COMPARISON object(dateRange) O dateRange associado a um período de comparação, se aplicável.

dateRange

{
  start: string,
  end: string
}

O objeto dateRange fornece informações sobre as datas de início e término de um período padrão ou de comparação.

Campo Tipo Descrição
start string Data de início do período no formato AAAAMMDD.
end string Data de término do período no formato AAAAMMDD.

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": {},
  "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"
      ]
    }
  }
}

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": {},
  "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"
      ]
    }
  }
}