連結 Looker Studio 中的所有資料，並以圖表呈現

1. 簡介

Looker Studio 可讓您免費建立即時互動式資訊主頁，並提供精美的資料視覺化效果。從各種來源擷取資料，並在 Looker Studio 中建立無限數量的報表，還能充分運用編輯和分享功能。以下是 Looker Studio 資訊主頁的範例螢幕截圖：

( 按這裡在 Looker Studio 中查看這個範例報表)

社群連接器是 Looker Studio 的一項功能，可讓您使用 Apps Script 建立連接器，連往任何可透過網際網路存取的資料來源。社群連接器是由 Looker Studio 社群建構而成，也就是說，任何人都可以建構社群連結器。您也可以與他人共用社群連結器，讓他們在 Looker Studio 中存取自己的資料。

您可以在不同用途中使用社群連結器：

您要將商業平台 (例如社群媒體、行銷、數據分析等) 的資料視覺化
您要將地端企業資料 (例如地端 MySQL 資料庫的銷售資料) 視覺化
您提供管道，讓顧客以視覺化方式呈現服務中的資料
您正在建立一鍵式報表平台
您要以視覺化方式呈現來自網路來源的資料 (例如建立 Google 健身資訊主頁)

課程內容

Looker Studio 社群連結器的運作方式
如何使用 Google Apps Script 建構社群連結器
如何在 Looker Studio 中使用社群連接器

軟硬體需求

連上網際網路並使用網路瀏覽器
Google 帳戶
熟悉基本 JavaScript 和 Web API

2. 簡短問卷調查

你為什麼選擇這個程式碼研究室？

我對一般資料視覺化感興趣。

我想進一步瞭解 Looker Studio

我想自行建立社群連接器。

我嘗試將 Looker Studio 與其他平台整合。

我對 Google Cloud 解決方案有興趣。

您打算如何使用這個程式碼研究室/教學課程？

快速瀏覽即可

閱讀並完成練習

您對 Looker Studio 的熟悉程度為何？

從未聽過

我知道是什麼，但從未使用過。

我經常使用這項功能。

我是專家級使用者。

以下哪一項敘述最符合您的背景？

開發人員

商業 / 財務 / 資料分析師

資料科學家 / 資料工程師

行銷 / 社群媒體 / 數位分析專家

設計師

其他

你可以前往下一頁提交問卷調查資訊。

3. 社群連接器總覽

Looker Studio 社群連接器可讓 Looker Studio 直接連線至任何可透過網際網路存取的資料來源。您可以連結至商業平台、公開資料集，或您自己的內部私人資料。社群連結器可透過 Web API、JDBC API、純文字檔案 (CSV、JSON、XML) 和 Apps Script 服務擷取資料。

假設您已在 npm 上發布套件，並想追蹤該套件每天的下載次數。在本程式碼研究室中，您將建構社群連結器，使用 npm 套件下載次數 API 擷取資料。接著，您可以在 Looker Studio 中使用社群連結器，建立資訊主頁來顯示下載次數。

4. 社群連接器工作流程

在基本社群連結器中，您會定義四個函式：

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

視工作流程的目前步驟而定，Looker Studio 會執行這些連接器函式，並在後續步驟中使用回應。以下影片將概略說明：

社群連結器的運作方式
工作流程中的不同步驟
呼叫不同函式時
Looker Studio 顯示不同使用者介面的時機
不同步驟中預期的使用者動作

觀看影片後，即可繼續進行程式碼研究室。

您不必記住這個工作流程，只要看看即可瞭解連接器中會發生什麼事。你隨時可以返回這個圖表。

在下一個步驟中，您將開始在 Google Apps Script 中建立連結器。您必須在 Apps Script UI 和本程式碼研究室之間來回切換。

5. 設定 Apps Script 專案

步驟 1：前往 Google Apps Script。

步驟 2：點選左上方的「+ 新專案」，建立新的 Apps Script 專案。

您會看到殼層專案，以及 Code.gs 檔案中的空白 myFunction 函式。

步驟 3：刪除 myFunction 函式。

步驟 4：為專案命名：

按一下頁面左上方的 Untitled project
輸入專案標題。

在 Code.gs 檔案中開始撰寫連線器程式碼。

6. 定義 getAuthType()

Looker Studio 需要瞭解連接器使用的驗證方法時，就會呼叫 getAuthType() 函式。這個函式應傳回連接器授權第三方服務時所需的驗證方法。

由於您使用的 API 不需要任何驗證，因此為您建構的 npm 下載連接器不需要向任何第三方服務進行驗證。複製下列程式碼，並新增至 Code.gs 檔案：

Code.gs

var cc = DataStudioApp.createCommunityConnector();

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

您在此表示連接器不需要任何第三方驗證 (AuthTypes.NONE)。如要查看所有支援的驗證方法，請參閱 AuthType() 參考資料。

7. 定義 getConfig()

連接器使用者必須先設定連接器，才能開始使用。getConfig() 函式回應會定義使用者看到的設定選項。Looker Studio 會呼叫 getConfig() 函式，取得連接器的設定詳細資料。Looker Studio 會根據 getConfig() 提供的回應，顯示連接器設定畫面並變更特定連接器行為。

在設定畫面中，您可以使用下列表單元素提供資訊或取得使用者輸入內容：

`TEXTINPUT`	輸入元素	單行文字方塊。
`TEXTAREA`	輸入元素	多行文字區域方塊。
`SELECT_SINGLE`	輸入元素	單選選項的下拉式選單。
`SELECT_MULTIPLE`	輸入元素	多選選項的下拉式選單。
`CHECKBOX`	輸入元素	單一核取方塊，可用於擷取布林值。
`INFO`	顯示元素	靜態純文字方塊，可用於向使用者提供操作說明或資訊。

使用 INFO 元素提供使用者操作說明，並使用 TEXTINPUT 元素從使用者取得輸入套件名稱。在 getConfig() 回應中，您會將這些表單元素歸類在 configParams 鍵底下。

由於您要連線的 API 需要日期做為參數，請在 getConfig() 回應中將 dateRangeRequired 設為 true。這會告知 Looker Studio，所有資料要求都應提供日期範圍。如果資料來源不需要日期做為參數，可以省略這項設定。

在 Code.gs 檔案中，將下列 getConfig() 程式碼新增至 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();
}

根據這些 configParams，在 Looker Studio 中使用連接器時，您應該會看到如下的設定畫面。但稍後會再詳細說明。

接著介紹下一個函式 - getSchema()。

8. 定義 getSchema()

Looker Studio 會呼叫 getSchema() 函式，取得與使用者所選連接器設定相關聯的結構定義。根據 getSchema() 提供的回應，Looker Studio 會向使用者顯示欄位畫面，列出連接器中的所有欄位。

針對連接器的任何特定設定，結構定義是連接器可提供資料的所有欄位清單。連接器可能會根據各種設定，傳回具有不同欄位的不同結構定義。結構定義可包含從 API 來源擷取的欄位、在 Apps Script 中計算的欄位，以及使用計算欄位公式在 Looker Studio 中計算的欄位。連結器會提供結構定義中每個欄位的中繼資料，包括：

欄位名稱
欄位的資料類型
語意資訊

如要瞭解詳情，請參閱 getSchema() 和 Field 參考資料。

視連接器擷取資料的方式而定，結構定義可能會在呼叫 getSchema() 時固定或動態計算。使用者定義的 getConfig() 設定參數會提供給 getSchema() 函式的 request 引數。

在本程式碼研究室中，您不需要存取 request 引數。在下一個區段中，您將為 getData() 函式編寫程式碼，進一步瞭解 request 引數。

連接器的結構定義是固定的，包含下列 3 個欄位：

`packageName`	使用者提供的 npm 套件名稱
`downloads`	npm 套件的下載次數
`day`	下載次數統計日期

下方是連接器的 getSchema() 程式碼。由於 getSchema() 和 getData() 都需要這項功能，因此 getFields() 輔助函式會將欄位建立作業抽象化。在 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 };
}

根據這個結構定義，在 Looker Studio 中使用連接器時，您應該會在 Looker Studio 欄位畫面中看到下列欄位。但稍後測試連接器時會再詳細說明。

接著介紹最後一個函式 - getData()。

9. 定義 getData()：第 1 部分

Looker Studio 每次需要擷取資料時，都會呼叫 getData() 函式。根據 getData() 提供的回應，Looker Studio 會在資訊主頁中算繪及更新圖表。在下列事件期間，系統可能會呼叫 getData()：

使用者將圖表新增至資訊主頁
使用者編輯圖表
使用者查看資訊主頁
使用者編輯相關聯的篩選器或資料控制項
Looker Studio 需要資料樣本

您不需要從這個頁面複製任何程式碼，因為您會複製完成的

getData()

程式碼。

瞭解 `request` 物件

Looker Studio 會在每次 getData() 呼叫時傳遞 request 物件。請參閱下方的 request 物件結構。這有助於您編寫 getData() 函式的程式碼。

`request` 物件結構

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

configParams 物件會包含 getConfig() 中定義且由使用者設定的參數設定值。
scriptParams 物件會包含與連接器執行相關的資訊。在本程式碼研究室中，您不需要使用這項功能。
如果要求 getConfig() 回應，dateRange 會包含要求的日期範圍。
fields 包含要求資料的欄位名稱清單。

以連接器來說，getData() 函式的範例 request 可能如下所示：

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

在上述 request 中，即使連接器結構定義有其他欄位，系統也只要求提供兩個欄位。getData()下一頁會顯示這項 getData() 呼叫的回應範例，以及一般 getData() 回應結構。

10. 定義 getData()：第 2 部分

在 getData()回應中，您必須提供所要求欄位的結構定義和資料。您會將程式碼分成三個區段：

為要求的欄位建立結構定義。
從 API 擷取及剖析資料。
轉換剖析的資料，並篩選出要求的欄位。

您不需要從這個頁面複製任何程式碼，因為您會複製完成的

getData()

下一頁的程式碼。

這是連接器的 getData() 結構。

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>
  };
}

為要求的欄位建立結構定義

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

從 API 擷取及剖析資料

npm API 網址的格式如下：

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

使用 Looker Studio 提供的 request.dateRange.startDate、request.dateRange.endDate 和 request.configParams.package 建立 API 的網址。然後使用 UrlFetchApp(Apps Script 類別：參考資料) 從 API 擷取資料。然後剖析擷取的回應。

  // 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;

轉換已剖析的資料，並篩選出要求的欄位

npm API 的回應格式如下：

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

轉換 npm API 的回應，並以以下格式提供 getData() 回應。如果對這個格式不清楚，請參閱下一個段落中的範例回應。

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

在回應中，使用 schema 屬性，只傳回所要求欄位的結構定義。您將使用 rows 屬性以資料列清單的形式傳回資料。每個資料列的 values 欄位順序必須與 schema 欄位順序一致。根據先前的 request 範例，getData() 的回應如下所示：

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

您已建立架構子集。使用下列函式轉換已剖析的資料，並篩選出所要求的欄位。

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. 定義 getData()：第 3 部分

合併後的 getData() 程式碼如下所示。在 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
  };
}

您已完成 Code.gs 檔案！接著，更新資訊清單。

12. 更新資訊清單

在 Apps Script 編輯器中，依序選取「專案設定」>「在編輯器中顯示『appsscript.json』資訊清單檔案」。

系統會建立新的 appsscript.json 資訊清單檔案。

將 appscript.json 檔案替換為下列內容：

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

儲存 Apps Script 專案。

恭喜！您已建構第一個社群連結器，現在可以開始測試！

13. 在 Looker Studio 中測試連接器

使用部署作業

步驟 1：在 Apps Script 開發環境中，依序點選「部署」 >「測試部署作業」，開啟「測試部署作業」對話方塊。

系統會列出預設部署作業「Head Deployment」。

步驟 2：按一下「複製」，複製標題部署 ID。

步驟 3：如要在 Looker Studio 中載入連接器，請在下列連結中將 <HEAD_DEPLOYMENT_ID> 預留位置替換為連接器的正式部署 ID，然後在瀏覽器中開啟該連結：

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

授權連接器

首次使用 Looker Studio 的使用者：如果您從未用過 Looker Studio，系統會要求您授權 Looker Studio，並同意相關條款及細則。完成授權程序。首次使用 Looker Studio 時，您也可能會看到更新行銷偏好的對話方塊。如要透過電子郵件接收最新功能相關資訊、最新消息和產品公告，請訂閱「產品公告」。

載入後，系統會提示您授權連結器。

按一下「授權」，並授予連接器必要的授權。

設定連接器

授權完成後，系統會顯示設定畫面。在文字輸入區中輸入「lighthouse」，然後按一下右上方的「連線」。

確認結構定義

系統會顯示「欄位」畫面。按一下右上方的「建立報表」。

建立資訊主頁

系統會將您帶往 Looker Studio 資訊主頁環境。按一下 [Add to Report] (加入報表)。

在 Looker Studio 中，每當使用者存取連接器並新增設定時，系統就會在該使用者的 Looker Studio 帳戶中建立新的資料來源。您可以將資料來源視為根據特定設定建立的連結器例項。根據使用者選取的連結器和設定，資料來源會傳回含有特定欄位組合的資料表。使用者可以透過同一個連接器建立多個資料來源。資料來源可供多份報表使用，同一份報表也能使用多個資料來源。

現在新增時序圖！在選單中，依序按一下「插入」>「時間序列」。然後將時間序列放在畫布上。您應該會看到所選套件的 npm 下載次數時間序列圖表。新增日期篩選器控制項，並查看資訊主頁，如下所示。

大功告成！您已建立第一個社群連接器！本程式碼研究室即將告一段落。接著，我們來看看可以採取哪些後續步驟。

14. 後續步驟

改善您建立的連接器

改善您剛才建立的連接器：

在 Looker Studio 中，如果您未在連接器的設定畫面中提供套件名稱，繪製時間序列圖表時就會看到錯誤訊息。請嘗試在連接器設定中新增輸入驗證或預設選項。
請嘗試在連接器設定中新增支援，以便同時查詢多個套件名稱。提示：npm 套件下載次數 API 支援以半形逗號分隔輸入多個套件名稱。
您可以在 npm 連接器程式碼中找到這兩種問題的解決方案。

充分運用社群連接器

查看連接器 API 和資訊清單的參考資料。
如要瞭解最佳做法，請參閱開放原始碼存放區中的連接器程式碼範例。
完成 clasp 程式碼研究室，即可在本機環境中開發社群連結器。
建構完整的社群連結器後，請考慮可用的發布選項。
為 Looker Studio 建立社群視覺化。

其他資源

下方提供各種資源，可協助您深入瞭解本程式設計實作室涵蓋的內容。

資源類型	使用者功能	開發人員功能
說明文件	說明中心	開發人員說明文件
最新消息與動態	在 Looker Studio 中註冊 > 使用者設定	開發人員郵寄清單
提問	使用者論壇	Stack Overflow [looker-studio]
影片	DataVis DevTalk
範例	報表庫連結器庫	開放原始碼存放區

連結 Looker Studio 中的所有資料，並以圖表呈現

1. 簡介

課程內容

軟硬體需求

2. 簡短問卷調查

你為什麼選擇這個程式碼研究室？

您打算如何使用這個程式碼研究室/教學課程？

您對 Looker Studio 的熟悉程度為何？

以下哪一項敘述最符合您的背景？

3. 社群連接器總覽

4. 社群連接器工作流程

5. 設定 Apps Script 專案

6. 定義 getAuthType()

Code.gs

7. 定義 getConfig()

Code.gs

8. 定義 getSchema()

Code.gs

9. 定義 getData()：第 1 部分

瞭解 request 物件

request 物件結構

10. 定義 getData()：第 2 部分

為要求的欄位建立結構定義

從 API 擷取及剖析資料

轉換已剖析的資料，並篩選出要求的欄位

11. 定義 getData()：第 3 部分

Code.gs

12. 更新資訊清單

appsscript.json

13. 在 Looker Studio 中測試連接器

使用部署作業

授權連接器

設定連接器

確認結構定義

建立資訊主頁

14. 後續步驟

改善您建立的連接器

充分運用社群連接器

其他資源

瞭解 `request` 物件

`request` 物件結構