Descripción general de la API
La biblioteca dscc
permite crear componentes comunitarios para Data Studio. El código fuente está disponible en GitHub.
dscc
expone tres funciones: getWidth()
, getHeight()
y subscribeToData()
.
getWidth()
Nombre | Parámetros | Tipo de resultado devuelto | Descripción |
---|---|---|---|
getWidth() | None | number
|
Devuelve la anchura del iframe en píxeles. |
Usar getWidth()
// to get the width of the iframe
var width = dscc.getWidth();
getHeight()
Nombre | Parámetros | Tipo de resultado devuelto | Descripción |
---|---|---|---|
getHeight() | None | int
|
Devuelve la altura del iframe en píxeles. |
Usar getHeight()
// to get the height of the iframe
var height = dscc.getHeight();
sendInteraction()
La función sendInteraction()
envía un mensaje a Data Studio con los datos de un filtro.
Parámetros:
Nombre | Tipo | Descripción |
---|---|---|
actionID | string
|
Cadena que corresponde a actionID en la configuración. |
interaction | enum(InteractionType)
|
Informa a Data Studio sobre la interacción. |
data | object(InteractionData)
|
Proporciona los datos necesarios para llevar a cabo una interacción. |
InteractionType
De momento, el único parámetro InteractionType
válido es FILTER
.
Nombre | Tipo | Descripción |
---|---|---|
dscc.InteractionType.FILTER | Enum | Describe la interacción FILTER . |
Usar 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 | Descripción |
---|---|---|
concepts | Array |
Matriz de fieldIds . |
values | Array<Array>
|
Matriz anidada de valores de datos. La longitud de cada submatriz debe coincidir con la de la matriz concepts .
Cada uno de los valores de la submatriz corresponde a un valor de dimensión. |
Ejemplo de interactionData
:
var interactionData = {
"concepts": ["dim1Id", "dim2Id"],
"values": [
["dim1Val1", "dim2Val1"],
["dim1Val2", "dim2Val2"]
]
}
Usar dscc.sendInteraction
con el objeto interactionData
indicado arriba equivale a la siguiente declaración SQL:
SELECT data WHERE
(dim1 == dim1Val1 AND dim2 == dim2Val1)
OR
(dim1 == dim1Val2 AND dim2 == dim2Val2);
clearInteraction()
La función clearInteraction()
envía un mensaje a Data Studio para borrar un filtro que esta visualización ha definido previamente.
Parámetros:
Nombre | Tipo | Descripción |
---|---|---|
actionID | string
|
Cadena que corresponde a actionID en la configuración. |
interaction | enum(InteractionType)
|
Informa a Data Studio sobre la interacción. |
Usar 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)
La función subscribeToData()
realiza la suscripción a los mensajes de Data Studio.
Parámetros:
Nombre | Tipo | Descripción |
---|---|---|
callback(data) | function
|
Función que recoge los datos que subscribeToData devuelve. |
options | object |
Define el formato que tendrán los datos devueltos. |
El objeto options tiene este aspecto:
{
transform: dscc.tableTransform | dscc.objectTransform
}
Valor devuelto:
Tipo | Descripción |
---|---|
function |
Cancela la suscripción de callback a mensajes futuros de Data Studio. |
Usar 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
Este es el objeto enviado al parámetro callback
, que está registrado con dscc.subscribeToData
. Estos son los campos que se comparten entre dscc.objectFormat
y dscc.tableFormat
.
{
fields: object(fieldsByConfigId),
style: object(styleById),
interactions: object(interactionsById),
theme: object(themeStyle),
tables: object(tablesById)
}
Campo | Tipo | Descripción |
---|---|---|
fields | object(fieldsByConfigId)
|
Objeto que contiene objetos field indexados por su configId. |
style | object(styleById)
|
Objeto que contiene objetos style indexados por su configId. |
interactions | object(interactionsById)
|
Objeto que contiene objetos interaction. |
theme | themeStyle
|
Objeto themeStyle que contiene información sobre estilo de temas del informe. |
tables | object(tablesById)
|
Objeto que contiene objetos tableObject. |
fieldsByConfigId
{
configId: array(field)
}
El objeto fieldsByConfigId
contiene matrices de objetos field indexados por el "id" que se ha definido en la configuración de la visualización. Hay una entrada en este objeto para cada objeto dataField
definido en la configuración.
Campo | Tipo | Descripción |
---|---|---|
configId | Array<field> |
Matriz de campos asociados con dataField. |
field
{
id: fieldId,
name: string,
description: string,
type: fieldType,
concept: enum(conceptType)
}
El objeto field
proporciona información sobre el campo que el usuario selecciona en el panel de propiedades.
Campo | Tipo | Descripción |
---|---|---|
id | string |
ID que Data Studio genera para el campo. |
name | string |
Nombre del campo legible por personas. |
description | string |
Descripción del campo. |
type | enum(fieldType) |
Tipo semántico (semanticType) del campo. |
concept | enum(conceptType) |
Tipo de concepto (conceptType) del campo. |
styleById
{
configId: styleValue
}
El objeto styleById
proporciona información de estilo indexada por el "id" que se ha definido en la configuración de visualización.
Campo | Tipo | Descripción |
---|---|---|
configId | styleValue
|
Objeto que contiene el valor de estilo y el valor de estilo predeterminado que se ha definido en la configuración. |
styleValue
{
value: string | object | bool | number,
defaultValue: string | object | bool | number
}
El objeto styleValue
proporciona tanto el valor de estilo que ha seleccionado el usuario como el valor predeterminado que se ha definido en la configuración. El tipo de value
y defaultValue
dependen del elemento style.
Campo | Tipo | Descripción |
---|---|---|
value | string OR object OR bool OR
number
|
Valor del elemento de estilo que ha devuelto la selección del usuario en el panel de propiedades. |
defaultValue | string OR object OR bool OR
number
|
Valor predeterminado del elemento de estilo que se ha definido en la configuración de la visualización. |
interactionsById
{
}
El objeto interactionsById
proporciona datos de interacción que ha indexado la configuración de visualización de interactionId
.
Índice | Tipo | Descripción |
---|---|---|
configId | interaction
|
Objeto que contiene datos asociados con una interacción. |
interactionField
{
value: object(interactionValue),
supportedActions: array(InteractionType)
}
El objeto interactionField
contiene la matriz de acciones supportedActions que se ha definido en la configuración, así como los valores que ha seleccionado el usuario para la interacción.
Campo | Tipo | Descripción |
---|---|---|
value | string OR object OR
bool OR number
|
Valor del elemento de estilo que ha devuelto la selección del usuario en el panel de propiedades. |
supportedActions | Array<InteractionType>
|
Acciones compatibles con esta interacción, según se han definido en la configuración. |
interactionValue
El objeto interactionValue
proporciona valores que ha seleccionado el usuario para el tipo de interacción en cuestión. Si existe la clave data
, el objeto InteractionData
refleja el estado del filtro en ese momento. Si no existe la clave data
, se debe a que la visualización no está configurada en ese momento como un filtro.
{
type: enum(InteractionType)
data: object(interactionData) | None
}
Campo | Tipo | Descripción |
---|---|---|
type | enum(InteractionType)
|
Función InteractionType que ha seleccionado el usuario. |
data | object(InteractionData)
|
El objeto data asociado con el estado del filtro. Esta clave no existe si el filtro se ha borrado. |
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
}
]
}
El objeto themeStyle
envía información sobre el tema del informe a la visualización.
Campo | Tipo | Descripción |
---|---|---|
fillColor | object
|
Objeto con el formato {color:
string, opacity: number} . |
fontColor | object
|
Objeto con el formato {color:
string, opacity: number} . |
accentFillColor | object
|
Objeto con el formato {color:
string, opacity: number} . |
accentFontColor | object
|
Objeto con el formato {color:
string, opacity: number} . |
fontFamily | string |
Cadena que describe el conjunto de fuentes. |
accentFontFamily | string
|
Cadena que describe el conjunto de fuentes con acento. |
increaseColor | object
|
Objeto con el formato {color:
string, opacity: number} . |
decreaseColor | object
|
Objeto con el formato {color:
string, opacity: number} . |
gridColor | object
|
Objeto con el formato {color:
string, opacity: number} . |
seriesColor | Array<object>
|
Matriz de objetos con el formato {color: string, opacity:
number} . |
tablesById
{
"DEFAULT": object(tableObject),
"COMPARISON": object(tableObject) | undefined
}
El objeto tableObject
proporciona información sobre el encabezado y los datos de cada fila. "DEFAULT" siempre devolverá datos, y "COMPARISON" solo se rellenará si el usuario configura los datos con filas de comparación.
El formato de tableObject es la única diferencia entre dscc.tableFormat
y dscc.objectFormat
.
Campo | Tipo | Descripción |
---|---|---|
"DEFAULT" | object(tableObject) OR
Array<objectRow>
|
Objeto tableObject asociado a los datos que un usuario añade a una visualización. |
"COMPARISON" | object(tableObject) OR
Array<objectRow>
|
Objeto tableObject asociado a los datos de comparación de fechas, si corresponde. |
Referencia de tableFormat
tableObject
{
headers: array(object),
rows: array(array)
}
Campo | Tipo | Descripción |
---|---|---|
headers | Array
|
Matriz de objetos field. Estos objetos tienen, además, una propiedad configId correspondiente a los ID de la configuración. |
rows | Array<Array> |
Matriz de matrices, donde cada matriz es una fila de datos. |
Datos tableFormat
de muestra
Se trata de datos (data
) de muestra que se devuelven al usar dscc.subscribeToData()
con la opció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": {},
"interactions": {
"onClick": {
"value": {
"type": "FILTER",
"data": {
"concepts": [
"qt_h6oibrb6wb",
"qt_i6oibrb6wb"
],
"values": [
[
"Afternoon",
"Sunday"
],
[
"Afternoon",
"Thursday"
],
[
"Morning",
"Tuesday"
]
]
}
},
"supportedActions": [
"FILTER"
]
}
}
}
Referencia de objectFormat
objectRow
{
configId1: array(string | bool | number),
configId2: array(string | bool | number)
}
Campo | Tipo | Descripción |
---|---|---|
configId | array | Matriz de valores asociada con un determinado ID de configuración. |
Datos objectFormat de muestra
Se trata de datos (data
) de muestra que se devuelven al usar dscc.subscribeToData()
con la opció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": {},
"interactions": {
"onClick": {
"value": {
"type": "FILTER",
"data": {
"concepts": [
"qt_h6oibrb6wb",
"qt_i6oibrb6wb"
],
"values": [
[
"Afternoon",
"Sunday"
],
[
"Afternoon",
"Thursday"
],
[
"Morning",
"Tuesday"
]
]
}
},
"supportedActions": [
"FILTER"
]
}
}
}