Referência da API Community Connector

Funções obrigatórias

getConfig()

Retorna as opções configuráveis pelo usuário para o conector.

Solicitação

@param {Object} request – Um objeto JavaScript que contém os parâmetros da solicitação de configuração.

O objeto JavaScript do parâmetro inclui dados com a seguinte estrutura:

{
      languageCode: string
    }
    

Nome do campo	Tipo	Descrição
languageCode	string	Código que representa o idioma do usuário. Ele pode ser utilizado para retornar uma versão localizada das opções de configuração para o usuário. Veja a lista completa dos idiomas e códigos compatíveis.
configParams	object	Usado se a chamada anterior para getConfig() incluiu .setIsSteppedConfig(true). Um objeto que contém os valores de configuração fornecidos pelo usuário até o momento.

Exemplo de solicitação

Exemplo de uma solicitação getConfig para um usuário cujo idioma está configurado como italiano:

{
      languageCode: "it"
    }
    

Resposta

Serviço do Data Studio

@return {object} – Um objeto JavaScript que representa a configuração da solicitação especificada.

Exemplo

function getConfig(request) {
      var cc = DataStudioApp.createCommunityConnector();
      var config = cc.getConfig();

      config
          .newTextInput()
          .setId('exampleTextInput')
          .setName('Single line text')
          .setHelpText('Helper text for single line text')
          .setPlaceholder('Lorem Ipsum');

      config
          .newTextArea()
          .setId('exampleTextArea')
          .setName('Text area')
          .setHelpText('Helper text for text area')
          .setPlaceholder('Lorem Ipsum');

      config
          .newSelectSingle()
          .setId('exampleSelectSingle')
          .setName('Select single')
          .setHelpText('Helper text for select single')
          .setAllowOverride(true)
          .addOption(config.newOptionBuilder().setLabel('Lorum foo').setValue('lorem'))
          .addOption(config.newOptionBuilder().setLabel('Ipsum Bar').setValue('ipsum'))
          .addOption(config.newOptionBuilder().setLabel('Sit').setValue('amet'));

      config
          .newSelectMultiple()
          .setId('exampleSelectMultiple')
          .setName('Select multiple')
          .setHelpText('Helper text for select multiple')
          .addOption(config.newOptionBuilder().setLabel('Lorum foo').setValue('lorem'))
          .addOption(config.newOptionBuilder().setLabel('Ipsum Bar').setValue('ipsum'))
          .addOption(config.newOptionBuilder().setLabel('Sit').setValue('amet'));

      config
          .newCheckbox()
          .setId('exampleCheckbox')
          .setName('This is a checkbox')
          .setHelpText('Helper text for checkbox');

      config
          .newInfo()
          .setId('exampleInfo')
          .setText('Examle instructions text used in Info')

      config.setDateRangeRequired(true);
      config.setIsSteppedConfig(false);

      return config.build();
    }
    

Legado

@return {object} – Um objeto JavaScript que representa a configuração do conector que será exibido ao usuário.

A resposta contém a configuração do conector com a seguinte estrutura:

  {
        configParams: [
          {
            type: string(ConfigType),
            name: string,
            displayName: string,
            helpText: string,
            placeholder: string,
            isDynamic: boolean,
            parameterControl: {
              allowOverride: boolean
            },
            options: [
              {
                label: string,
                value: string
              }
            ]
          }
        ],
        dateRangeRequired: boolean,
        isSteppedConfig: boolean
      }
    

Nome do campo	Tipo	Descrição
configParams[]	object	O usuário informou os valores exigidos pelo conector. Cada item representa um campo de entrada do usuário.
configParams[].type	string (ConfigType)	Tipo de campo de entrada.
configParams[].name	string	ID do campo de entrada. Uma string com algum valor e sem espaços.
configParams[].displayName	string	Etiqueta de texto para o campo de entrada.
configParams[].helpText	string	Texto a ser exibido para oferecer mais ajuda ao usuário com relação ao valor esperado no campo.
configParams[].placeholder	string	Usado somente quando type for TEXTINPUT ou TEXTAREA Texto do marcador a ser utilizado como uma breve sugestão para descrever o valor esperado no campo de entrada.
configParams[].isDynamic	boolean	Indica se esse campo é usado ou não para preencher dinamicamente entradas de configuração posteriores. O valor padrão é false.
configParams[].parameterControl.allowOverride	boolean	Permite modificar o parâmetro. Quando definido como true, os criadores de fontes de dados poderão ativá-lo para os editores de relatórios O valor padrão de allowOverride é false. Se você não quiser ativar a modificação de um parâmetro, omita a propriedade allowOverride.
configParams[].options[]	list	Usado somente se type for SELECT Ele exibe a lista de todas as opções.
options[].label	string	O rótulo da opção.
options[].value	string	O valor da opção. String com algum valor, sem espaços e sem vírgulas.
dateRangeRequired	boolean	Se o valor for true, um período será fornecido para solicitações getData(). Por padrão, o período é definido como os últimos 28 dias excluindo today. Defina esse campo para APIs de dados que requerem um período para acompanhar as consultas e se as solicitações de API de dados forem mais eficientes devido à limitação do período. O valor padrão é false.
isSteppedConfig	boolean	Se o valor for true, o Data Studio solicitará que o usuário responda ao conjunto atual de perguntas de configuração e depois retornará as perguntas respondidas nas chamadas subsequentes para getConfig(). Se o valor for false (padrão), o usuário poderá clicar em "Conectar" e acessar a página "Esquema".

Exemplo de resposta

O exemplo a seguir mostra a configuração de uma caixa de texto de linha única, uma área de texto, uma seleção única, uma seleção múltipla, uma caixa de seleção e uma caixa de informações. É possível modificar o valor de seleção única nos relatórios.

  {
        configParams: [
          {
            type: "TEXTINPUT",
            name: "exampleTextInput",
            displayName: "Single line text",
            helpText: "Helper text for single line text",
            placeholder: "Lorem Ipsum"
          },
          {
            type: "TEXTAREA",
            name: "exampleTextArea",
            displayName: "Text area",
            helpText: "Helper text for text area",
            placeholder: "Lorem Ipsum"
          },
          {
            type: "SELECT_SINGLE",
            name: "exampleSELECT_SINGLE",
            displayName: "Select single",
            helpText: "Helper text for select-single",
            parameterControl: {
              allowOverride: true
            },
            options: [
              {
                label: "Lorem foo",
                value: "lorem"
              },
              {
                label: "Ipsum bar",
                value: "ipsum"
              },
              {
                label: "Sit",
                value: "amet"
              }
            ]
          },
          {
            type: "SELECT_MULTIPLE",
            name: "exampleSELECT_MULTIPLE",
            displayName: "Select multiple",
            helpText: "Helper text for select-multiple",
            options: [
              {
                label: "Lipsum",
                value: "lipsum"
              },
              {
                label: "Foo Bar",
                value: "foobar"
              },
              {
                label: "Dolor Sit",
                value: "amet"
              }
            ]
          },
          {
            type: "CHECKBOX",
            name: "exampleCheckbox",
            displayName: "This is a checkbox",
            helpText: "Helper text for checkbox",
          },
          {
            type: "INFO",
            name: "exampleInfo",
            text: "Example instructions text used in Info"
          }
        ],
        dateRangeRequired: false
      }
    

getSchema()

Retorna o esquema para a solicitação fornecida. Envia informações sobre como os dados do conector estão organizados. Detalhes, como identificadores, nomes e tipos de dados, são incluídos em todos os campos.

Solicitação

@param {Object} request – Um objeto JavaScript que contém os parâmetros de solicitação do esquema.

O objeto JavaScript do parâmetro inclui dados com a seguinte estrutura:

{
      "configParams": object
    }
    

Nome do campo	Tipo	Descrição
configParams	Object	Um objeto JavaScript que contém os valores fornecidos pelo usuário para os parâmetros de configuração definidos pelo conector.

Observação: SELECT_MULTIPLE é uma string separada por vírgulas. Por exemplo, se foo e bar forem selecionados, o padrão será "foo,bar". Valores CHECKBOX são retornados como um valor verdadeiro.

Exemplo de solicitação

Exemplo de um objeto de solicitação getSchema:

{
      "configParams": {
        "exampleSelectMultiple": "foobar,amet",
        "exampleSelectSingle": "ipsum",
        "exampleTextInput": "Lorem Ipsum Dolor Sit Amet",
        "exampleTextArea": "NA",
        "exampleCheckbox": "true"
      }
    }
    

Resposta

Serviço do Data Studio

@return {object} – Um objeto JavaScript que representa o esquema da solicitação especificada.

Exemplo

function getSchema(request) {
      var cc = DataStudioApp.createCommunityConnector();
      var fields = cc.getFields();
      var types = cc.FieldType;

      var created = fields.newDimension()
          .setId('Created')
          .setName('Date Created')
          .setDescription('The date that this was created')
          .setType(types.YEAR_MONTH_DAY)
          .setGroup('Date');

      var amount = fields.newMetric()
          .setId('Amount')
          .setName('Amount (USD)')
          .setDescription('The cost in US dollars')
          .setType(types.CURRENCY_USD)
          .setIsHidden(true);

      var amountper = fields.newMetric()
          .setId('AmountPer')
          .setName('Amount Per Dimension')
          .setDescription('The summed cost')
          .setType(types.CURRENCY_USD)
          .setGroup('Money')
          .setFormula('sum($Amount)');

      var probability = fields.newMetric()
          .setId('Probability')
          .setName('Probability (Close rate)')
          .setDescription('The probability that a store closes')
          .setType(types.PERCENT);

      var opportunityname = fields.newDimension()
          .setId('OpportunityName')
          .setName('Opportunity Name')
          .setDescription('The name of the opportunity')
          .setType(types.TEXT);

      var isverified = fields.newDimension()
          .setId('IsVerified')
          .setName('Verified Status')
          .setDescription('Whether or not the store is verified')
          .setType(types.BOOLEAN);

      var company = fields.newDimension()
          .setId('Company')
          .setName('Incorporated Company Name')
          .setDescription('The name of the company the store belongs to')
          .setType(types.TEXT);

      fields.setDefaultMetric(amountper.getId());
      fields.setDefaultDimension(created.getId());

      return { 'schema': fields.build() };
    }
    

Legado

@return {object} – Um objeto JavaScript que representa o esquema da solicitação especificada.

A função retorna o esquema com a seguinte estrutura:

  {
        "schema": [
          {
            object(Field)
          }
        ]
      }
    

Nome do campo	Tipo	Descrição
schema[]	object(Field)	O esquema para a solicitação em questão, que inclui detalhes sobre cada campo.

Exemplo de resposta

  {
        "schema": [
          {
            "name": "Created",
            "label": "Date Created",
            "description": "The date that this was created",
            "dataType": "STRING",
            "group": "Date",
            "isDefault": true,
            "semantics": {
              "conceptType": "DIMENSION",
              "semanticGroup": "DATE_AND_TIME",
              "semanticType": "YEAR_MONTH_DAY",
              "isReaggregatable": false
            }
          },
          {
            "name": "Amount",
            "label": "Amount (USD)",
            "description": "The cost in US dollars",
            "dataType": "NUMBER",
            "isHidden": true,
            "semantics": {
              "conceptType": "METRIC",
              "semanticGroup": "CURRENCY",
              "semanticType": "CURRENCY_USD",
            }
          },
          {
            "name": "AmountPer",
            "label": "Amount Per Dimension",
            "description": "The summed cost",
            "dataType": "NUMBER",
            "group": "Money",
            "formula": "sum(Amount)",
            "isDefault": true,
            "semantics": {
              "conceptType": "METRIC",
              "semanticGroup": "CURRENCY",
              "semanticType": "CURRENCY_USD",
              "isReaggregatable": true
            }
          },
          {
            "name": "Probability",
            "label": "Probability (Close rate)",
            "description": "The probability that a store closes",
            "dataType": "NUMBER",
            "semantics": {
              "conceptType": "METRIC",
              "semanticGroup": "NUMERIC",
              "semanticType": "PERCENT",
              "isReaggregatable": false
            }
          },
          {
            "name": "OpportunityName",
            "label": "Opportunity Name",
            "description": "The name of the opportunity",
            "dataType": "STRING",
            "semantics": {
              "conceptType": "DIMENSION",
              "semanticType": "TEXT",
              "isReaggregatable": false
            }
          },
          {
            "name": "IsVerified",
            "label": "Verified Status",
            "description": "Whether or not the store is verified",
            "dataType": "BOOLEAN",
            "semantics": {
              "conceptType": "DIMENSION",
              "semanticType": "BOOLEAN",
              "isReaggregatable": false
            }
          },
          {
            "name": "Company",
            "label": "Incorporated Company Name",
            "description": "The name of the company the store belongs to",
            "dataType": "STRING",
            "semantics": {
              "conceptType": "DIMENSION",
              "semanticType": "TEXT",
              "isReaggregatable": false
            }
          }
        ]
      }
    

getData()

Retorna os dados tabulares para a solicitação em questão.

Observação: getData() pode retornar até um milhão de linhas/registros.

Solicitação

@param {Object} request – Um objeto JavaScript que contém os parâmetros de solicitação de dados.

O parâmetro request contém valores fornecidos pelo usuário e informações adicionais que podem ser utilizadas para processar a solicitação de dados. Ele tem a seguinte estrutura:

{
      "configParams": object,
      "scriptParams": {
        "sampleExtraction": boolean,
        "lastRefresh": string
      },
      "dateRange": {
        "startDate": string,
        "endDate": string
      },
      "fields": [
        {
          "name": string
        }
      ],
      "dimensionsFilters": [
        [{
          "fieldName": string,
          "values": string[],
          "type": DimensionsFilterType,
          "operator": Operator
        }]
      ]
    }
    

Nome	Tipo	Descrição
configParams	object	Um objeto que contém os valores fornecidos pelo usuário para os parâmetros de configuração definidos pelo conector.
scriptParams	ScriptParams	Um objeto que contém as informações relevantes para a execução do conector.
dateRange	DateRange	Por padrão, o período fornecido inclui os últimos 28 dias, excluindo hoje. Se um usuário aplicar um filtro de período em um relatório, o período inserido será aquele selecionado. Quando sampleExtraction é definido como true**, a data de dois dias antes da data atual é aplicada como data de início e término.
fields[].name	string	Nomes dos campos solicitados.
fields[].forFilterOnly	boolean	Marca um campo usado apenas para filtrar a solicitação. Não retorne o campo se o conector aplicar filtros.
dimensionsFilters	DimensionsFilters	Uma matriz aninhada dos filtros selecionados pelo usuário. As matrizes mais internas precisam ser separadas pela função OR, e as mais externas, por AND.

dateRange

Nome	Tipo	Descrição
startDate	string	Data de início da filtragem dos dados. Usado somente se dateRangeRequired estiver definido como true. O valor precisa estar no formato YYYY-MM-DD.
endDate	string	Data de término para filtrar os dados. Usado somente se dateRangeRequired estiver definido como true. O valor precisa estar no formato YYYY-MM-DD.

scriptParams

Nome	Tipo	Descrição
sampleExtraction	boolean	Se o valor for true, a solicitação getData() será usada para detecção automática do tipo semântico.
lastRefresh	string	Um carimbo de data/hora que marca a solicitação mais recente de uma atualização de dados.

dimensionFilters

Nome	Tipo	Descrição
fieldName	string	Nome do campo que será filtrado.
values	string[]	Matriz de valores a serem usados no operador.
type	"INCLUDE" | "EXCLUDE"	Informa se os dados que correspondem a esse filtro precisam ser incluídos ou excluídos da resposta de getData().
operator	FilterOperator	Operador que será aplicado.

Observação: se houver mais de 20 campos na solicitação, várias solicitações "getData" serão enviadas. Elas serão agrupadas a cada 20 campos.

Exemplo de solicitação

Observação: os nomes dos campos correspondem aos nomes fornecidos por getSchema(). Normalmente, as solicitações de dados incluem um subconjunto de campos do esquema.

{
      "configParams": {
        "multiSelectExample": "foo,bar",
        "singleSelectExample": "Lipsum",
        "singleTextExample": "Lorem Ipsum",
        "multiTextExample": "Dolor Sit Amet",
        "includeCheckExample": "true"
      },
      "dateRange": {
        "endDate": "2017-07-16",
        "startDate": "2017-06-19"
      },
      "fields": [
        {"name": "count"},
        {"name": "family"}
      ]
    }

    

Resposta

Padrão

@return {object} – Um objeto JavaScript que contém o esquema e os dados da solicitação fornecida.

A função retorna dados tabulares que atendem à solicitação enviada. O esquema dos dados tabulares é incluído na resposta. A resposta terá a seguinte estrutura:

  {
        "schema": [
          {
            object(Field)
          }
        ],
        "rows": [
          {
            "values": [
              string
            ]
          }
        ]
      }
    

Nome	Tipo	Descrição
schema	Campo[]	Esquema dos campos solicitados. field.name e field.dataType são obrigatórios. A ordem do objeto field precisa corresponder à ordem dos valores de cada linha.
rows[].values[]	string | number | boolean	Valores dos campos solicitados. A ordem dos valores precisa corresponder à ordem de Fields definido no schema.
filtersApplied	boolean	Defina como "true" se todos os filtros foram aplicados. Caso contrário, use "false".

Campo

Nome	Tipo	Descrição
name	string	Nome do campo.
dataType	DataType	Tipo do campo.

Exemplo

Observação: a ordem dos valores das linhas na resposta precisa corresponder àquela dos campos do esquema.

{
      "schema": [
        {
          "name": "OpportunityName",
          "dataType": "STRING"
        },
        {
          "name": "IsVerified",
          "dataType": "BOOLEAN"
        },
        {
          "name": "Created",
          "dataType": "STRING"
        },
        {
          "name": "Amount",
          "dataType": "NUMBER"
        }
      ],
      "rows": [
        {
          "values": ["Interesting", true, "2017-05-23", "120453.65"]
        },
        {
          "values": ["SF", false, "2017-03-03", "362705286.92"]
        },
        {
          "values": ["Spring Sale", true, "2017-04-21", "870.12"]
        }
      ],
      "filtersApplied": false
    }
    

BigQuery

@return {object} – Um objeto JavaScript que representa a configuração de consulta do BigQuery.

Exemplo

var bqTypes = DataStudioApp.createCommunityConnector().BigQueryParameterType;
    var configuration = DataStudioApp.createCommunityConnector().newBigQueryConfig()
        .setBillingProjectId('billingProjectId')
        .setQuery('myQueryString')
        .setUseStandardSql(true)
        .setAccessToken('myAccessToken')
        .addQueryParameter('myUrlParameterName', bqTypes.STRING, 'myUrlParameterValue')
        .build();
    

getAuthType()

Retorna o método de autenticação do conector.

Request

Esta função não aceita argumentos.

Resposta

Serviço do Data Studio

@return {object} – Um objeto que contém o AuthType usado pelo conector. Se o valor de AuthType for USER_TOKEN, USER_PASS ou KEY, um helpUrl opcional também poderá ser definido.

Exemplo

function getAuthType() {
      var cc = DataStudioApp.createCommunityConnector();
      return cc.newAuthTypeResponse()
        .setAuthType(cc.AuthType.USER_PASS)
        .setHelpUrl('https://www.example.org/connector-auth-help')
        .build();
    }
    

Legado

@return {object} – Um objeto que contém o AuthType usado pelo conector. Se o valor de AuthType for USER_TOKEN, USER_PASS ou KEY, um helpUrl opcional também poderá ser definido.

A resposta tem a seguinte estrutura:

 {
       "type": string(AuthType),
       "helpUrl": string
     }
    

Nome do campo	Tipo	Descrição
type	string(AuthType)	Valor do tipo de autenticação.
helpUrl	string	Um URL opcional que será exibido ao usuário se type for USER_TOKEN, USER_PASS ou KEY. Esse URL precisa direcionar a uma página em que os usuários possam ver detalhes sobre como autenticar o conector.

Exemplo de resposta

{
      "type": "USER_TOKEN",
      "helpUrl": "https://www.example.org/connector-auth-help"
    }
    

Funções de autenticação obrigatórias

isAuthValid()

Verifica se as credenciais do serviço de terceiros são válidas.

Request

Esta função não aceita formalmente nenhum argumento.

Resposta

@return {boolean} – Retorna true se as credenciais de serviço de terceiros forem válidas. Caso contrário, será false. Se o valor for true, as chamadas para getData e getSchema serão autorizadas. Caso ele seja false, o usuário será notificado de que a autenticação expirou e precisará reautorizá-la.

resetAuth()

Apaga as credenciais do usuário para o serviço de terceiros.

Request

Esta função não aceita formalmente nenhum argumento.

Resposta

A resposta está vazia.

Funções do OAuth 2.0 obrigatórias

get3PAuthorizationUrls()

Retorna o URL de autorização para iniciar o fluxo do OAuth 2.0 para o serviço de terceiros.

Solicitação

Esta função não aceita formalmente nenhum argumento.

Resposta

@return {string} – Retorna o URL de autorização do serviço de terceiros. O URL de autorização será exibido ao usuário para iniciar o fluxo do OAuth 2.0 de modo a conceder acesso ao serviço de terceiros.

Observação: um URL de autorização sempre precisará ser retornado, independentemente do status de autenticação atual.

authCallback()

Lida com a resposta de autorização recebida do serviço de terceiros como parte do processo de autorização OAuth 2.0.

Solicitação

@param {string} request – Um objeto JSON codificado que representa os dados de solicitação da conclusão do fluxo do OAuth 2.0.

O parâmetro request da conclusão de um fluxo OAuth 2.0 precisa ter a estrutura a seguir. Há duas representações abaixo, uma para uma solicitação bem-sucedida e outra para uma solicitação com falha:

// Success
    {
      "parameter":
        {
          "code": string
        }
    }

    // Error
    {
      "parameter":
        {
          "error": string
        }
    }
    

Nome do campo	Tipo	Descrição
parameter	object	Valores code ou error de um fluxo OAuth 2.0 bem-sucedido ou com falha. Eles podem ser usados para processamento adicional do callback.
code	string	Em um fluxo do OAuth 2.0 bem-sucedido, ele estará presente e conterá o valor do parâmetro de consulta code da solicitação de callback do OAuth 2.0 recebida do serviço de terceiros. É um código de autorização que pode ser usado para processamento adicional do OAuth 2.0.
error	object	Em uma tentativa do fluxo do OAuth 2.0 com falha, ele estará presente e conterá o valor do parâmetro de consulta error da solicitação de callback do OAuth 2.0 recebida do serviço de terceiros. Essa mensagem de erro pode ser usada para processamento adicional do OAuth 2.0 e criação de notificações.

Resposta

@return {object} – Retorna um objeto HTML que será processado e exibido ao usuário. Para mais detalhes, consulte a documentação da biblioteca do OAuth e a documentação do serviço HTML do Apps Script (ambos em inglês).

Funções obrigatórias de usuário/senha e chave

setCredentials()

Armazena as credenciais transmitidas para o Data Studio.

Solicitação

@param {Object} request – Um objeto JavaScript que contém os parâmetros de solicitação de dados.

O parâmetro request contém as credenciais inseridas pelo usuário. Ele utilizará userPass, userToken ou key, dependendo da resposta de getAuthType().

{
      "userPass": {
        "username": string,
        "password": string
      },
      "userToken": {
        "username": string,
        "token": string,
      },
      "key": string
    }
    

Nome do campo	Tipo
userPass.username	Nome de usuário que foi inserido.
userPass.password	Senha inserida pelo usuário.
userToken.username	Nome de usuário que foi inserido.
userToken.token	Token inserido pelo usuário.
key	Chave ou token da API inserido pelo usuário.

Resposta

@return {object} – Um objeto JavaScript que contém um código de erro indicando se as credenciais foram definidas com sucesso.

{
      "errorCode": string("NONE" | "INVALID_CREDENTIALS")
    }
    

Nome do campo	Tipo	Descrição
errorCode	enum(string)	Código de erro da chamada setCredentials.

Nome do código de erro	Descrição
"NONE"	Foi possível definir as credenciais.
"INVALID_CREDENTIALS"	As credenciais inseridas eram inválidas.

Exemplo de resposta

{
      "errorCode": "NONE"
    }
    

Funções opcionais

isAdminUser()

Verifica se o usuário é um administrador do conector. Esta função é usada para ativar/desativar recursos de depuração. Consulte Como ativar/desativar recursos de depuração para mais detalhes.

Solicitação

Esta função não aceita argumentos.

Resposta

@return {boolean} – Retorna true se o usuário for um administrador do conector. Se a função foi omitida ou retornou false, então o usuário não é um administrador. Consulte Como ativar/desativar recursos de depuração para mais detalhes.

Tipos de dados

Campo

Serviço do Data Studio

Veja o campo da classe de todos os métodos que existem no tipo do campo.

Como criar um campo

var cc = DataStudioApp.createCommunityConnector();
    var types = cc.FieldType;
    var aggregations = cc.AggregationType;

    var myField = cc.newDimension() // Or newMetric
      .setId('my_unique_identifier')
      .setName('My friendly name')
      .setDescription('My short description')
      .setType(types.YEAR_MONTH_DAY)
      // formula fields cannot be hidden.
      .setIsHidden(true)
      .setGroup('My group name');
    

Legado

Descreve um campo específico de um registro/linha como parte de um esquema.

Cada campo tem a seguinte estrutura:

{
      "name": string,
      "label": string,
      "description": string,
      "dataType": string(DataType),
      "group": string,
      "formula": string,
      "isDefault": boolean,
      "defaultAggregationType": string(DefaultAggregationType),
      "semantics": {
        "conceptType": string(ConceptType),
        "semanticType": string(SemanticType),
        "semanticGroup": string(SemanticGroup),
        "isReaggregatable": boolean
      }
    }
    

Nome do campo	Tipo	Descrição
name	string	Nome do campo. Ele é usado como um identificador exclusivo. Somente caracteres alfanuméricos e sublinhados são permitidos.
label	string	Nome de exibição do campo. Ele é usado como um nome "amigável" na IU.
description	string	Descrição opcional do campo. Somente texto simples é permitido.
dataType	string(DataType)	Tipo de dados do campo.
isHidden	boolean	Propriedade opcional. Defina como true para ocultar o campo. Os campos ocultos não são exibidos na tela nem como uma opção selecionável nos gráficos, mas podem ser usados em fórmulas de campo calculado. Não é possível ocultar campos de fórmula.
group	string	Propriedade opcional que indica que um campo pertence a um grupo. Se fieldA e fieldB pertencerem a groupC, eles serão agrupados no "Seletor da métrica" ou no "Seletor de dimensões" da IU. Se o grupo for definido para pelo menos um campo, os campos desagrupados ficarão em Default Group.
formula	string	Propriedade opcional que determina como um campo é calculado. Quando a fórmula é inválida, o campo é descartado. Se as duas propriedades de agregação (isReaggregatable e defaultAggregationType) e o formula forem fornecidos, as propriedades serão ignoradas. Apenas alguns semanticType aceitam o campo formula. É recomendável que os valores deles sejam textos ou números, exceto date e geo. Se a saída de texto de uma fórmula de data ou de informações geográficas corresponder a um tipo semântico, esse tipo semântico poderá ser usado. Caso contrário, ele precisará ser string. Se você definir este campo manualmente, ele não poderá ser editado no editor de campos. Para mais detalhes sobre a criação de fórmulas, consulte o artigo Sobre os campos calculados.
isDefault	boolean	Propriedade opcional que indica se um campo precisa ser selecionado como o padrão dimension ou metric. Defina apenas um padrão dimension e um metric para o esquema.
defaultAggregationType	string(DefaultAggregationType)	Propriedade opcional que indica qual agregação o Data Studio usará como padrão para este campo. Os usuários podem alterar esse valor.
semantics	object	Propriedades para fornecer informações semânticas sobre o campo. Se essa propriedade e semantics.semanticType estiverem presentes em qualquer um dos campos no esquema, a detecção automática da semântica será desativada. Se a propriedade não estiver presente em nenhum campo, a detecção automática da semântica será ativada.
semantics.conceptType	string(ConceptType)	Indica se o campo é uma dimensão ou uma métrica.
semantics.semanticType	string(SemanticType)	Tipo semântico do campo. Quando essa opção é informada, a detecção automática da semântica é desativada.
semantics.semanticGroup	string(SemanticGroup)	Grupo semântico do campo. Com essa propriedade opcional, é possível agrupar os tipos semânticos. No momento, o Data Studio não usa este campo, mas talvez comece a utilizá-lo no futuro.
semantics.isReaggregatable	boolean	true indica que a Agregação pode ser aplicada a este campo. No Data Studio, a Agregação é definida como SUM por padrão, e o usuário consegue alterá-la. false indica que a Agregação não pode ser aplicada a este campo. No Data Studio, a Agregação está definida como Automática por padrão, e o usuário não pode alterá-la. O valor padrão é true. Observação: esta propriedade afeta somente os campos de métrica.

ConceptType

Os valores para os tipos de conceito semântico podem ser um dos seguintes:

Valor de enum	Descrição
DIMENSION	Uma dimensão. As dimensões são categorias de dados que contêm valores como nomes, descrições ou outras características de uma categoria.
METRIC	Uma métrica. As métricas medem os valores de dimensão e representam medidas como soma, contagem, proporção etc.

DataType

Os valores para tipos de dados de esquema podem ser um dos seguintes:

Valor de enum	Descrição
STRING	Uma string arbitrária. Ela é definida pela especificação do esquema JSON.
NUMBER	Um tipo de dados numéricos no formato de ponto flutuante de 64 bits de dupla precisão (IEEE 754).
BOOLEAN	Valor booleano, true ou false. É definida pela especificação do esquema JSON.

SemanticType

Valor de enum	Descrição	Exemplo
YEAR	YYYY	"2017"
YEAR_QUARTER	YYYYQ	"20171"
YEAR_MONTH	YYYYMM	"201703"
YEAR_WEEK	YYYYww	"201707"
YEAR_MONTH_DAY	YYYYMMDD	"20170317"
YEAR_MONTH_DAY_HOUR	YYYYMMDDHH	"2017031403"
YEAR_MONTH_DAY_SECOND	YYYYMMDDHHMMSS	"20170314031545"
QUARTER	(1, 2, 3, 4)	"1"
MONTH	MM	"03"
WEEK	ww	"07"
MONTH_DAY	MMDD	"0317"
DAY_OF_WEEK	Um número decimal de 0 a 6, em que 0 representa domingo.	"0"
DAY	DD	"17"
HOUR	HH	"02"
MINUTE	mm	"12"
DURATION	Duração (em segundos)	6340918234
COUNTRY	País	"United States"
COUNTRY_CODE	Código do país	"US"
CONTINENT	Continente	"Americas"
CONTINENT_CODE	Código do continente	"019"
SUB_CONTINENT	Subcontinente	"North America"
SUB_CONTINENT_CODE	Código do subcontinente	"003"
REGION	Região	"California"
REGION_CODE	Código da região	"CA"
CITY	Cidade	"Mountain View"
CITY_CODE	Código da cidade	"1014044"
METRO_CODE	Código da área metropolitana	"200807"
LATITUDE_LONGITUDE	Latitude e longitude	"51.5074, -0.1278"
NUMBER	Número decimal	14
PERCENT	Percentual decimal (pode ser superior a 1,0)	1.0
TEXT	Texto livre	"Here is some text"
BOOLEAN	true ou false	true
URL	URL em formato de texto	"https://www.google.com"

Tipos semânticos de fórmula

Valor de enum	Descrição	Fórmula
HYPERLINK	Link com uma etiqueta de texto	"HYPERLINK($url, $description)"
IMAGE	URL de uma imagem	"IMAGE($image_url, $alt_text)"
IMAGELINK	Link com uma etiqueta de imagem	"HYPERLINK($url, $image_field)"

Observação: veja os documentos HYPERLINK e IMAGE na Central de Ajuda para mais informações.

Tipos semânticos de moeda

Todos os valores de moeda são números de JavaScript. Valores negativos são permitidos.

Valor de enum	Descrição
CURRENCY_AED	Dirham dos Emirados Árabes Unidos (dh)
CURRENCY_ALL	Lek albanês (lek)
CURRENCY_ARS	Pesos argentinos ($)
CURRENCY_AUD	Dólar australiano ($)
CURRENCY_BDT	Taka de Bangladesh (৳)
CURRENCY_BGN	Lev búlgaro (lev)
CURRENCY_BOB	Pesos bolivianos (Bs)
CURRENCY_BRL	Real brasileiro (R$)
CURRENCY_CAD	Dólar canadense ($)
CURRENCY_CDF	Franco congolês (FrCD)
CURRENCY_CHF	Franco suíço (CHF)
CURRENCY_CLP	Peso chileno ($)
CURRENCY_CNY	Yuan chinês (¥)
CURRENCY_COP	Peso colombiano ($)
CURRENCY_CRC	Colón costa-riquenho (₡)
CURRENCY_CZK	Coroa tcheca (Kč)
CURRENCY_DKK	Coroa dinamarquesa (kr.)
CURRENCY_DOP	Peso dominicano (RD$)
CURRENCY_EGP	Libra egípcia (£)
CURRENCY_ETB	Birr etíope (Birr)
CURRENCY_EUR	Euro (€)
CURRENCY_GBP	Libra esterlina (£)
CURRENCY_HKD	Dólar de Hong Kong ($)
CURRENCY_HRK	Kuna croata (kn)
CURRENCY_HUF	Florim húngaro (Ft)
CURRENCY_IDR	Rúpia indonésia (Rp)
CURRENCY_ILS	Novo Shekel israelense (₪)
CURRENCY_INR	Rúpia indiana (₹)
CURRENCY_IRR	Rial iraniano (Rial)
CURRENCY_ISK	Coroa islandesa (kr)
CURRENCY_JMD	Dólar jamaicano ($)
CURRENCY_JPY	Iene japonês (¥)
CURRENCY_KRW	Won sul-coreano (₩)
CURRENCY_LKR	Rúpia do Sri Lanka (Rs)
CURRENCY_LTL	Litas da Lituânia (Lt)
CURRENCY_MNT	Tugrik da Mongólia (₮)
CURRENCY_MVR	Rupia das Maldivas (Rf)
CURRENCY_MXN	Peso mexicano ($)
CURRENCY_MYR	Ringgit da Malásia (RM)
CURRENCY_NOK	Coroa norueguesa (kr)
CURRENCY_NZD	Dólares da Nova Zelândia ($)
CURRENCY_PAB	Balboa panamenho (B/.)
CURRENCY_PEN	Novo sol peruano (S/.)
CURRENCY_PHP	Peso filipino (₱)
CURRENCY_PKR	Rúpia paquistanesa (Rs)
CURRENCY_PLN	Zloti polonês (zł)
CURRENCY_RON	Leu romeno (RON)
CURRENCY_RSD	Dinar sérvio (din)
CURRENCY_RUB	Rublo russo (₽)
CURRENCY_SAR	Rial da Arábia Saudita (Rial)
CURRENCY_SEK	Coroa sueca (kr)
CURRENCY_SGD	Dólar de Cingapura ($)
CURRENCY_THB	Baht tailandês (฿)
CURRENCY_TRY	Lira turca (₺)
CURRENCY_TWD	Novo dólar de Taiwan (NT$)
CURRENCY_TZS	Xelim tanzaniano (TSh)
CURRENCY_UAH	Hryvnia da Ucrânia (грн.)
CURRENCY_USD	Dólar americano ($)
CURRENCY_UYU	Dólar americano ($)
CURRENCY_VEF	Peso uruguaio ($)
CURRENCY_VND	Bolívar venezuelano (Bs)
CURRENCY_YER	Dong vietnamita (₫)
CURRENCY_ZAR	Rial do Iêmen (Rial)

SemanticGroup

Esta é apenas uma lista de valores sugeridos, você pode escolher outros valores não inclusos nela. No entanto, definir este campo não modificará o grupo que o Data Studio usa na opção Type para o editor de campos.

Valor sugerido	Descrição
NUMERIC	Grupo Numeric
DATETIME	Grupo DateTime
GEO	Grupo Geo
CURRENCY	Grupo Currency

DefaultAggregationType

Valor de enum	Descrição
AVG	A média numérica (média) das entradas.
COUNT	O número de entradas.
COUNT_DISTINCT	O número de entradas distintas.
MAX	O máximo de entradas.
MIN	O mínimo de entradas.
SUM	A soma das entradas.
NONE	Sem agregação.
AUTO	Precisa ser definido para os campos calculados que envolvem uma agregação.

Observação: AUTO só pode ser usado em campos calculados. Veja os campos desse tipo.

AuthType

Os valores para o tipo de método de autenticação podem ser um dos seguintes:

Valor de enum	Descrição
NONE	Indica que a autenticação não é necessária para o conector.
OAUTH2	Indica que o conector usa o OAuth 2.0 para autenticação.
KEY	Indica que o conector usa a chave de API para autenticação.
USER_PASS	Indica que o conector utiliza o nome de usuário/senha para autenticação.
USER_TOKEN	Indica que o conector utiliza o nome de usuário/token para autenticação.

ConfigType

Os valores para os tipos de elementos do formulário de configuração podem ser um dos seguintes:

Valor de enum	Descrição
TEXTINPUT	O elemento de entrada será uma caixa de texto de linha única.
TEXTAREA	O elemento de entrada será uma caixa textarea de várias linhas.
SELECT_SINGLE	O elemento de entrada será um menu suspenso para opções de seleção única.
SELECT_MULTIPLE	O elemento de entrada será um menu suspenso para opções de várias seleções.
CHECKBOX	O elemento de entrada será uma caixa de seleção única que pode ser usada para capturar valores booleanos.
INFO	Esta é uma caixa de texto simples estática que pode ser usada para dar instruções ou informações ao usuário. Todos os links são clicáveis.

Operador de filtro

Operador
EQUALS
CONTAINS
REGEXP_PARTIAL_MATCH
REGEXP_EXACT_MATCH
IN_LIST
IS_NULL
BETWEEN
NUMERIC_GREATER_THAN
NUMERIC_GREATER_THAN_OR_EQUAL
NUMERIC_LESS_THAN
NUMERIC_LESS_THAN_OR_EQUAL

EQUALS

O valor de comparação corresponde exatamente ao valor de dimensão.

Cláusula de exemplo:

{
        "operator": "EQUALS",
        "type": "INCLUDE",
        "values": ["USA"],
        "fieldName": "Country"
    }
    

Atenção: values é uma Array, não uma string

única.

Dados anteriores à aplicação do filtro:

País	Cidade
USA	Seattle
CA	Montreal
ROK	Seul

Dados depois de aplicar o filtro:

País	Cidade
USA	Seattle

CONTAINS

O valor de comparação está contido no valor de dimensão.

Cláusula de exemplo:

{
        "operator": "CONTAINS",
        "type": "INCLUDE",
        "values": ["A"],
        "fieldName": "COUNTRY"
    }
    

Dados antes de aplicar o filtro:

País	Cidade
USA	Seattle
CA	Montreal
ROK	Seul

Dados depois de aplicar o filtro:

País	Cidade
USA	Seattle
CA	Montreal

REGEXP_PARTIAL_MATCH

O valor de dimensão contém a expressão regular.

Cláusula de exemplo:

{
        "operator": "REGEXP_PARTIAL_MATCH",
        "type": "INCLUDE",
        "values": ["(?i)R[A-Z]*"],
        "fieldName": ""
    }
    

Dados antes de aplicar o filtro:

País	Cidade
USA	Seattle
CA	Montreal
ROK	Seul
RU	Moscou

Dados depois de aplicar o filtro:

País	Cidade
ROK	Seul
RU	Moscou

REGEXP_EXACT_MATCH

O valor de dimensão corresponde à expressão regular.

Cláusula de exemplo:

{
        "operator": "REGEXP_EXACT_MATCH",
        "type": "INCLUDE",
        "values": ["^R[A-Z]*K$"],
        "fieldName": ""
    }
    

Dados antes de aplicar o filtro:

País	Cidade
USA	Seattle
CA	Montreal
ROK	Seul
RU	Moscou

Dados depois de aplicar o filtro:

País	Cidade
ROK	Seul

IN_LIST

Um ou mais dos valores de comparação fazem correspondência exata com o valor de dimensão.

Cláusula de exemplo:

{
        "operator": "IN_LIST",
        "type": "INCLUDE",
        "values": ["USA", "CA"],
        "fieldName": "Country"
    }
    

Dados antes de aplicar o filtro:

País	Cidade
USA	Seattle
CA	Montreal
ROK	Seul

Dados depois de aplicar o filtro:

País	Cidade
USA	Seattle
CA	Montreal

IS_NULL

Faz correspondência se o valor de dimensão é nulo.

Cláusula de exemplo:

{
        "operator": "IS_NULL",
        "type": "INCLUDE",
        "values": [],
        "fieldName": "COUNTRY"
    }
    

Dados antes de aplicar o filtro:

País	Cidade
USA	Seattle
CA	Montreal
ROK	Seul
RU	Moscou
	Terabítia

Dados depois de aplicar o filtro:

País	Cidade
	Terabítia

BETWEEN

Faz correspondência se o valor de dimensão está entre os dois valores de teste.

Cláusula de exemplo:

{
        "operator": "BETWEEN",
        "type": "INCLUDE",
        "values": ["20190101", "20190131"],
        "fieldName": "Date"
    }
    

Dados antes de aplicar o filtro:

País	Data
USA	20190101
USA	20190111
USA	20190201

Dados depois de aplicar o filtro:

País	Data
USA	20190101
USA	20190111

NUMERIC_GREATER_THAN

Faz correspondência se o valor de dimensão é maior do que o de teste.

Cláusula de exemplo:

{
        "operator": "NUMERIC_GREATER_THAN",
        "type": "INCLUDE",
        "values": ["20190101"],
        "fieldName": "Date"
    }
    

Dados antes de aplicar o filtro:

País	Data
USA	20190101
USA	20190111
USA	20190201

Dados depois de aplicar o filtro:

País	Data
USA	20190111
USA	20190201

NUMERIC_GREATER_THAN_OR_EQUAL

Faz correspondência se o valor de dimensão é maior ou igual ao de teste.

Cláusula de exemplo:

{
        "operator": "NUMERIC_GREATER_THAN_OR_EQUAL",
        "type": "INCLUDE",
        "values": ["20190101"],
        "fieldName": "Date"
    }
    

Dados antes de aplicar o filtro:

País	Data
USA	20180101
USA	20190101
USA	20190111
USA	20190201

Dados depois de aplicar o filtro:

País	Data
USA	20190101
USA	20190111
USA	20190201

NUMERIC_LESS_THAN

Faz correspondência se o valor de dimensão é menor ou igual ao de teste.

Cláusula de exemplo:

{
        "operator": "NUMERIC_LESS_THAN",
        "type": "INCLUDE",
        "values": ["20190101"],
        "fieldName": "Date"
    }
    

Dados antes de aplicar o filtro:

País	Data
USA	20180101
USA	20190101
USA	20190111
USA	20190201

Dados depois de aplicar o filtro:

País	Data
USA	20180101

NUMERIC_LESS_THAN_OR_EQUAL

Faz correspondência se o valor de dimensão é menor ou igual ao de teste.

Cláusula de exemplo:

{
        "operator": "NUMERIC_LESS_THAN_OR_EQUAL",
        "type": "INCLUDE",
        "values": ["20190101"],
        "fieldName": "Date"
    }
    

Dados antes de aplicar o filtro:

País	Data
USA	20180101
USA	20190101
USA	20190111
USA	20190201

Dados depois de aplicar o filtro:

País	Data
USA	20180101
USA	20190101