Connettere e visualizzare tutti i tuoi dati in Data Studio

1. Introduzione

Data Studio ti consente di creare senza costi dashboard interattive e live con visualizzazioni dei dati accattivanti. Recupera i dati da una serie di origini e crea report illimitati in Data Studio, con funzionalità complete di modifica e condivisione. Lo screenshot seguente mostra un esempio di dashboard di Data Studio:

( Fai clic qui per visualizzare questo report di esempio in Data Studio)

I connettori della community sono una funzionalità di Data Studio che ti consente di utilizzare Apps Script per creare connettori per qualsiasi origine dati accessibile da internet. I connettori della community sono creati dalla community di Data Studio. Ciò significa che chiunque può creare connettori della community. Puoi anche condividere i connettori della community con altre persone in modo che possano accedere ai propri dati da Data Studio.

Puoi utilizzare i connettori della community in diversi casi d'uso:

• Stai visualizzando i dati di una piattaforma commerciale (ad es.social media, marketing, analisi e così via).
• Visualizzi dati aziendali on-premise (ad es. dati di vendita di un database MySQL on-premise)
• Offri ai tuoi clienti un modo per visualizzare i dati del tuo servizio
• Stai creando una piattaforma di segnalazione con pulsante
• Visualizzi i tuoi dati da un'origine web (ad es. crei la dashboard di Google Fit)

Obiettivi didattici

• Come funziona un connettore della community di Data Studio
• Come utilizzare Google Apps Script per creare un connettore della community
• Come utilizzare i connettori della community in Data Studio

Che cosa ti serve

• Accesso a internet e a un browser web
• Un Account Google
• Familiarità con le API JavaScript e web di base

2. Quick Survey

Perché hai scelto questo codelab?

Mi interessa la visualizzazione dei dati in generale. Voglio saperne di più su Data Studio Voglio creare un mio connettore della community. Sto cercando di integrare Data Studio con un'altra piattaforma. Sono interessato alle soluzioni Google Cloud.

Come prevedi di utilizzare questo codelab/tutorial?

Solo una lettura veloce Leggi e completa gli esercizi

Come valuteresti la tua familiarità con Data Studio?

Non ne ho mai sentito parlare So cos'è, ma non lo uso. Lo utilizzo regolarmente. Sono un utente esperto.

Quale opzione descrive meglio il tuo background?

Sviluppatore Analista aziendale / finanziario / di dati Data scientist / Data engineer Esperto di marketing / social media / analisi digitale Designer Altro

Puoi passare alla pagina successiva per inviare le informazioni del sondaggio.

3. Panoramica dei connettori della community

I connettori della community di Data Studio consentono connessioni dirette da Data Studio a qualsiasi origine dati accessibile da internet. Puoi connetterti a piattaforme commerciali, set di dati pubblici o ai tuoi dati privati on-premise. I connettori della community possono recuperare i dati tramite API web, API JDBC, file flat (CSV, JSON, XML) e servizi Apps Script.

Considera uno scenario in cui hai pubblicato un pacchetto su npm e vuoi monitorare il numero di download del pacchetto nel tempo per giorno. In questo codelab, creerai un connettore della community che recupera i dati utilizzando l'API del numero di download dei pacchetti npm. Il connettore della community può quindi essere utilizzato in Data Studio per creare un dashboard per visualizzare i conteggi dei download.

4. Flusso di lavoro del connettore della community

In un connettore della community di base, definirai quattro funzioni:

• getAuthType()
• getConfig()
• getSchema()
• getData()

A seconda del passaggio attuale del flusso di lavoro, Data Studio esegue queste funzioni del connettore e utilizza la risposta nei passaggi successivi. Il video che segue fornisce una panoramica di:

• Come funziona un connettore della community
• Diversi passaggi del flusso di lavoro
• Quando vengono chiamate funzioni diverse
• Quando Data Studio mostra interfacce utente diverse
• Azioni utente previste in diverse fasi

Puoi riprendere il codelab dopo aver guardato il video.

Non è necessario memorizzare questo flusso di lavoro, basta dare un'occhiata per capire cosa succede in un connettore. Puoi sempre tornare a questo diagramma.

Nel passaggio successivo, inizierai a creare il connettore in Google Apps Script. Dovrai passare dall'UI di Apps Script a questo codelab e viceversa.

5. Configura il progetto Apps Script

Passaggio 1: visita Google Apps Script.

Passaggio 2: crea un nuovo progetto Apps Script facendo clic su "+ Nuovo progetto" nella sezione in alto a sinistra.

Vedrai un progetto shell con una funzione myFunction vuota nel file Code.gs.

Passaggio 3: elimina la funzione myFunction.

Passaggio 4: assegna un nome al progetto:

1. Fai clic su Untitled project in alto a sinistra nella pagina.
2. Inserisci un titolo per il progetto.

Inizia a scrivere il codice del connettore nel file Code.gs.

6. Definisci getAuthType()

Data Studio chiamerà la funzione getAuthType() quando deve conoscere il metodo di autenticazione utilizzato dal connettore. Questa funzione deve restituire il metodo di autenticazione richiesto dal connettore per autorizzare il servizio di terze parti.

Per il connettore di download npm che stai creando, non è necessario autenticarsi con alcun servizio di terze parti, poiché l'API che utilizzi non richiede alcuna autenticazione. Copia il seguente codice e aggiungilo al file Code.gs:

Code.gs

var cc = DataStudioApp.createCommunityConnector();

function getAuthType() {
  var AuthTypes = cc.AuthType;
  return cc
    .newAuthTypeResponse()
    .setAuthType(AuthTypes.NONE)
    .build();
}

In questo caso, indichi che il connettore non richiede alcuna autenticazione di terze parti (AuthTypes.NONE). Per visualizzare tutti i metodi di autenticazione supportati, consulta il riferimento AuthType().

7. Definisci getConfig()

Gli utenti del tuo connettore dovranno configurarlo prima di poterlo utilizzare. La risposta della funzione getConfig() definisce le opzioni di configurazione che gli utenti vedranno. Data Studio chiama la funzione getConfig() per ottenere i dettagli di configurazione del connettore. In base alla risposta fornita da getConfig(), Data Studio visualizzerà la schermata di configurazione del connettore e modificherà il comportamento di alcuni connettori.

Nella schermata di configurazione, puoi fornire informazioni o ricevere input dell'utente utilizzando i seguenti elementi del modulo:

TEXTINPUT	Elemento di input	Una casella di testo su una sola riga.
TEXTAREA	Elemento di input	Una casella di testo multilinea.
SELECT_SINGLE	Elemento di input	Un menu a discesa per le opzioni di selezione singola.
SELECT_MULTIPLE	Elemento di input	Un menu a discesa per le opzioni di selezione multipla.
CHECKBOX	Elemento di input	Una singola casella di controllo che può essere utilizzata per acquisire valori booleani.
INFO	Elemento display	Una casella di testo statico che può essere utilizzata per fornire istruzioni o informazioni all'utente.

Utilizza l'elemento INFO per fornire le istruzioni all'utente e l'elemento TEXTINPUT per ottenere il nome del pacchetto di input dall'utente. Nella risposta getConfig(), raggrupperai questi elementi del modulo sotto la chiave configParams.

Poiché l'API a cui ti connetti richiede la data come parametro, imposta dateRangeRequired su true nella risposta getConfig(). In questo modo Data Studio fornisce intervalli di date con tutte le richieste di dati. Se l'origine dati non richiede la data come parametro, puoi ometterla.

Aggiungi il seguente codice getConfig() al file Code.gs, sotto il codice esistente per getAuthType():

Code.gs

function getConfig(request) {
  var config = cc.getConfig();
  
  config.newInfo()
    .setId('instructions')
    .setText('Enter npm package names to fetch their download count.');
  
  config.newTextInput()
    .setId('package')
    .setName('Enter a single package name')
    .setHelpText('e.g. googleapis or lighthouse')
    .setPlaceholder('googleapis');
  
  config.setDateRangeRequired(true);
  
  return config.build();
}

In base a questi parametri di configurazione, quando utilizzi il connettore in Data Studio, puoi aspettarti di visualizzare una schermata di configurazione come la seguente. Ma ne parleremo più avanti.

Passiamo alla funzione successiva: getSchema().

8. Definisci getSchema()

Data Studio chiama la funzione getSchema() per ottenere lo schema associato alla configurazione selezionata dall'utente per il connettore. In base alla risposta fornita da getSchema(), Data Studio mostrerà all'utente la schermata dei campi con tutti i campi del connettore.

Per qualsiasi configurazione specifica del connettore, lo schema è un elenco di tutti i campi per i quali il connettore può fornire dati. Un connettore potrebbe restituire uno schema diverso con campi diversi in base a varie configurazioni. Lo schema può contenere campi recuperati dall'origine API, campi calcolati in Apps Script e campi calcolati in Data Studio utilizzando una formula del campo calcolato. Il connettore fornisce i metadati su ogni campo dello schema, tra cui:

• Nome del campo
• Tipo di dati per il campo
• Informazioni semantiche

Per saperne di più, consulta i riferimenti getSchema() e Field in un secondo momento.

A seconda di come viene recuperato il connettore, lo schema può essere fisso o calcolato dinamicamente quando viene chiamato getSchema(). I parametri di configurazione di getConfig() definiti dall'utente verranno forniti nell'argomento request per la funzione getSchema().

Per questo codelab, non è necessario accedere all'argomento request. Nel segmento successivo, scoprirai di più sull'argomento request quando scrivi il codice per la funzione getData().

Per il connettore, lo schema è fisso e contiene i seguenti tre campi:

packageName	Nome del pacchetto npm fornito dall'utente
downloads	Conteggio dei download del pacchetto npm
day	Data del conteggio dei download

Di seguito è riportato il codice getSchema() per il connettore. La funzione helper getFields() astrae la creazione dei campi, poiché questa funzionalità è necessaria sia per getSchema() che per getData(). Aggiungi il seguente codice al file Code.gs:

Code.gs

function getFields(request) {
  var cc = DataStudioApp.createCommunityConnector();
  var fields = cc.getFields();
  var types = cc.FieldType;
  var aggregations = cc.AggregationType;
  
  fields.newDimension()
    .setId('packageName')
    .setType(types.TEXT);
  
  fields.newMetric()
    .setId('downloads')
    .setType(types.NUMBER)
    .setAggregation(aggregations.SUM);
  
  fields.newDimension()
    .setId('day')
    .setType(types.YEAR_MONTH_DAY);
  
  return fields;
}

function getSchema(request) {
  var fields = getFields(request).build();
  return { schema: fields };
}

In base a questo schema, quando utilizzi il connettore in Data Studio, nella schermata dei campi di Data Studio dovresti visualizzare i seguenti campi. Ma ne parleremo più avanti, quando testerai il connettore.

Passiamo alla nostra ultima funzione: getData().

9. Definisci getData() : parte 1

Data Studio chiama la funzione getData() ogni volta che deve recuperare i dati. In base alla risposta fornita da getData(), Data Studio eseguirà il rendering e l'aggiornamento dei grafici nella dashboard. getData() potrebbe essere chiamato durante questi eventi:

• L'utente aggiunge un grafico alla dashboard
• L'utente modifica un grafico
• L'utente visualizza la dashboard
• L'utente modifica un filtro o un controllo dei dati associato
• Data Studio ha bisogno di un campione di dati

Non è necessario copiare alcun codice da questa pagina, poiché copierai il codice completato

getData()

codice in un passaggio successivo.

Comprendere l'oggetto request

Data Studio passa l'oggetto request a ogni chiamata getData(). Esamina la struttura dell'oggetto request riportato di seguito. In questo modo, potrai scrivere il codice per la funzione getData().

Struttura dell'oggetto request

{
  configParams: object,
  scriptParams: object,
  dateRange: {
    startDate: string,
    endDate: string
  },
  fields: [
    {
      name: Field.name
    }
  ]
}

• L'oggetto configParams conterrà i valori di configurazione per i parametri definiti in getConfig() e configurati dall'utente.
• L'oggetto scriptParams conterrà informazioni pertinenti all'esecuzione del connettore. Non è necessario utilizzarlo per questo codelab.
• dateRange conterrà l'intervallo di date richiesto, se richiesto nella risposta getConfig().
• fields conterrà l'elenco dei nomi dei campi per i quali vengono richiesti i dati.

Per il tuo connettore, un esempio di request della funzione getData() potrebbe avere il seguente aspetto:

{
  configParams: {
    package: 'jquery'
  },
  dateRange: {
    startDate: '2017-07-16',
    endDate: '2017-07-18'
  },
  fields: [
    {
      name: 'day',
    },
    {
      name: 'downloads',
    }
  ]
}

Per la chiamata getData() nel request precedente, vengono richiesti solo due campi, anche se lo schema del connettore ne ha altri. La pagina successiva conterrà la risposta di esempio per questa chiamata getData() e la struttura generale della risposta getData().

Nota

In questo codelab non utilizziamo il parametro request per getSchema(). Per getSchema(), il parametro request conterrà solo configParams e scriptParams.

10. Definisci getData() : parte 2

Nella getData()risposta, dovrai fornire sia lo schema sia i dati per i campi richiesti. Dividi il codice in tre segmenti:

• Crea uno schema per i campi richiesti.
• Recupera e analizza i dati dall'API.
• Trasforma i dati analizzati e filtra i campi richiesti.

Non è necessario copiare alcun codice da questa pagina, poiché copierai il codice completato

getData()

codice nella pagina successiva.

Questa è la struttura di getData() per il tuo connettore.

function getData(request) {

  // TODO: Create schema for requested fields.
  
  // TODO: Fetch and parse data from API.
  
  // TODO: Transform parsed data and filter for requested fields.

  return {
    schema: <filtered schema>,
    rows: <transformed and filtered data>
  };
}

Crea uno schema per i campi richiesti

// Create schema for requested fields
  var requestedFieldIds = request.fields.map(function(field) {
    return field.name;
  });
  var requestedFields = getFields().forIds(requestedFieldIds);

Recuperare e analizzare i dati dall'API

L'URL dell'API npm sarà nel seguente formato:

https://api.npmjs.org/downloads/point/{start_date}:{end_date}/{package}

Crea l'URL per l'API utilizzando request.dateRange.startDate, request.dateRange.endDate e request.configParams.package forniti da Data Studio. Quindi, recupera i dati dall'API utilizzando UrlFetchApp(classe Apps Script: riferimento). Quindi analizza la risposta recuperata.

  // Fetch and parse data from API
  var url = [
    'https://api.npmjs.org/downloads/range/',
    request.dateRange.startDate,
    ':',
    request.dateRange.endDate,
    '/',
    request.configParams.package
  ];
  var response = UrlFetchApp.fetch(url.join(''));
  var parsedResponse = JSON.parse(response).downloads;

Trasforma i dati analizzati e filtra i campi richiesti

La risposta dell'API npm avrà il seguente formato:

{
  downloads: [
    {
    day: '2014-02-27',
    downloads: 1904088
    },
    ..
    {
    day: '2014-03-04',
    downloads: 7904294
    }
  ],
  start: '2014-02-25',
  end: '2014-03-04',
  package: 'somepackage'
}

Trasforma la risposta dell'API npm e fornisci la risposta getData() nel seguente formato. Se questo formato non è chiaro, dai un'occhiata alla risposta di esempio nel paragrafo seguente.

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

Nella risposta, restituisci lo schema solo per i campi richiesti utilizzando la proprietà schema. Restituirai i dati utilizzando la proprietà rows come elenco di righe. Per ogni riga, la sequenza di campi in values deve corrispondere alla sequenza di campi in schema. In base all'esempio precedente di request, ecco come apparirà la risposta per getData():

{
  schema: requestedFields.build(),
  rows: [
    {
      values: [ 38949, '20170716']
    },
    {
      values: [ 165314, '20170717']
    },
    {
      values: [ 180124, '20170718']
    },
  ]
}

Hai già creato il sottoinsieme dello schema. Utilizza la seguente funzione per trasformare i dati analizzati e filtrarli per i campi richiesti.

function responseToRows(requestedFields, response, packageName) {
  // Transform parsed data and filter for requested fields
  return response.map(function(dailyDownload) {
    var row = [];
    requestedFields.asArray().forEach(function (field) {
      switch (field.getId()) {
        case 'day':
          return row.push(dailyDownload.day.replace(/-/g, ''));
        case 'downloads':
          return row.push(dailyDownload.downloads);
        case 'packageName':
          return row.push(packageName);
        default:
          return row.push('');
      }
    });
    return { values: row };
  });
}

11. Definisci getData() : parte 3

Il codice getData() combinato sarà simile a quello riportato di seguito. Aggiungi il seguente codice al file Code.gs:

Code.gs

function responseToRows(requestedFields, response, packageName) {
  // Transform parsed data and filter for requested fields
  return response.map(function(dailyDownload) {
    var row = [];
    requestedFields.asArray().forEach(function (field) {
      switch (field.getId()) {
        case 'day':
          return row.push(dailyDownload.day.replace(/-/g, ''));
        case 'downloads':
          return row.push(dailyDownload.downloads);
        case 'packageName':
          return row.push(packageName);
        default:
          return row.push('');
      }
    });
    return { values: row };
  });
}

function getData(request) {
  var requestedFieldIds = request.fields.map(function(field) {
    return field.name;
  });
  var requestedFields = getFields().forIds(requestedFieldIds);

  // Fetch and parse data from API
  var url = [
    'https://api.npmjs.org/downloads/range/',
    request.dateRange.startDate,
    ':',
    request.dateRange.endDate,
    '/',
    request.configParams.package
  ];
  var response = UrlFetchApp.fetch(url.join(''));
  var parsedResponse = JSON.parse(response).downloads;
  var rows = responseToRows(requestedFields, parsedResponse, request.configParams.package);

  return {
    schema: requestedFields.build(),
    rows: rows
  };
}

Hai finito con il file Code.gs. Ora aggiorna il manifest.

12. Aggiorna manifest

Nell'editor Apps Script, seleziona Impostazioni progetto > Mostra il file manifest "appsscript.json" nell'editor.

Verrà creato un nuovo file manifest appsscript.json.

Sostituisci il file appscript.json con quanto segue:

appsscript.json

{
  "timeZone": "America/Los_Angeles",
  "exceptionLogging": "STACKDRIVER",
  "runtimeVersion": "V8",

  "dataStudio": {
    "name": "npm Downloads - From Codelab",
    "logoUrl": "https://raw.githubusercontent.com/npm/logos/master/npm%20logo/npm-logo-red.png",
    "company": "Codelab user",
    "companyUrl": "https://developers.google.com/looker-studio/",
    "addonUrl": "https://github.com/googledatastudio/example-connectors/tree/master/npm-downloads",
    "supportUrl": "https://github.com/googledatastudio/community-connectors/issues",
    "description": "Get npm package download counts.",
    "sources": ["npm"]
  }
}

Salva il progetto Apps Script.

Complimenti! Hai creato il tuo primo connettore della community ed è pronto per un test drive.

13. Testare il connettore in Data Studio

Utilizzare il deployment

Passaggio 1: nell'ambiente di sviluppo Apps Script, fai clic su Esegui il deployment > Testa i deployment per aprire la finestra di dialogo Testa i deployment.

Verrà visualizzato il deployment predefinito, Head Deployment.

Passaggio 2: fai clic su Copia per copiare l'ID deployment dell'intestazione.

Passaggio 3:per caricare il connettore in Data Studio, sostituisci il segnaposto <HEAD_DEPLOYMENT_ID> nel seguente link con l'ID deployment head del connettore e segui il link nel browser:

https://lookerstudio.google.com/datasources/create?connectorId=<HEAD_DEPLOYMENT_ID>

Autorizza il connettore

Utenti di Data Studio per la prima volta:se non hai mai utilizzato Data Studio, ti verrà chiesto di autorizzare Data Studio e di accettare i termini e le condizioni. Completa la procedura di autorizzazione. Quando utilizzi Data Studio per la prima volta, potresti anche visualizzare una finestra di dialogo per aggiornare le tue preferenze di marketing. Registrati per ricevere gli annunci dei prodotti se vuoi ricevere via email informazioni sulle ultime funzionalità, sugli aggiornamenti e sugli annunci dei prodotti.

Una volta caricato, vedrai un messaggio che ti chiede di autorizzare il connettore.

Fai clic su Autorizza e fornisci l'autorizzazione richiesta al connettore.

Importante: quando autorizzi il connettore, potresti visualizzare il seguente avviso: "Google non ha verificato questa app". Poiché sei l'autore del connettore, puoi continuare il flusso di autorizzazione facendo clic su Avanzate -> Vai a <nome del progetto> (non sicuro) nella parte inferiore della finestra di dialogo.

Configura il connettore

Una volta completata l'autorizzazione, verrà visualizzata la schermata di configurazione. Digita "lighthouse" nell'area di inserimento del testo e fai clic su Connetti in alto a destra.

Conferma lo schema

Viene visualizzata la schermata dei campi. Fai clic su Crea report in alto a destra.

Creazione di una dashboard

Ti troverai nell'ambiente della dashboard di Data Studio. Fai clic su Aggiungi al report.

In Data Studio, ogni volta che un utente accede a un connettore e aggiunge una nuova configurazione, viene creata una nuova origine dati nell'account Data Studio dell'utente. Puoi considerare un'origine dati come un'istanza del connettore basata su una configurazione specifica. In base al connettore e alla configurazione selezionati dall'utente, un'origine dati restituirà una tabella di dati con un insieme specifico di campi. Gli utenti possono creare più origini dati dallo stesso connettore. Un'origine dati può essere utilizzata in più report e lo stesso report può utilizzare più origini dati.

Ora aggiungi un grafico delle serie temporali. Nel menu, fai clic su Inserisci > Serie temporali. Poi posiziona la serie temporale nel canvas. Dovresti visualizzare un grafico delle serie temporali del conteggio dei download di npm per il pacchetto selezionato. Aggiungi un controllo filtro per la data e visualizza la dashboard come mostrato di seguito.

È tutto. Hai appena creato il tuo primo connettore della community. Siamo arrivati alla fine di questo codelab. Ora vediamo quali sono i passaggi successivi che puoi intraprendere.

14. Passaggi successivi

Migliorare il connettore che hai creato

Apporta miglioramenti al connettore che hai appena creato:

• In Data Studio, se non fornisci un nome del pacchetto nella schermata di configurazione del connettore, visualizzerai un messaggio di errore quando disegni il grafico delle serie temporali. Prova ad aggiungere la convalida dell'input o un'opzione predefinita alla configurazione del connettore.
• Prova ad aggiungere il supporto per l'interrogazione di più nomi di pacchetti contemporaneamente nella configurazione del connettore. Suggerimento: l'API per il conteggio dei download dei pacchetti npm supporta l'inserimento di più nomi di pacchetti separati da virgole.
• Puoi trovare le soluzioni a entrambi i problemi nel codice del nostro connettore npm.

Ottieni di più con i connettori della community

• Visualizza il riferimento per l'API del connettore e il manifest.
• Esplora il codice del connettore di esempio nel nostro repository open source per comprendere le best practice.
• Completa il Codelab clasp per poter sviluppare connettori della community nel tuo ambiente locale.
• Una volta creato un connettore della community completo, valuta le opzioni di pubblicazione disponibili.
• Crea una visualizzazione della community per Data Studio.

Risorse aggiuntive

Di seguito sono riportate varie risorse a cui puoi accedere per approfondire il materiale trattato in questo codelab.

Tipo di risorsa	Funzionalità utente	Funzionalità per sviluppatori
Documentazione	Centro assistenza	Documentazione per gli sviluppatori
Notizie e aggiornamenti	Registrati in Data Studio > Impostazioni utente	Mailing list per gli sviluppatori
Fai domande	Forum degli utenti	Stack Overflow [looker-studio]
Video	DataVis DevTalk
Esempi	Galleria report Galleria dei connettori	Repository open source