JavaScript 快速入门

快速入门介绍了如何设置和运行调用 Google Workspace API 的应用。

Google Workspace 快速入门使用 API 客户端库来处理身份验证和授权流程的某些详细信息。我们建议您为自己的应用使用客户端库。本快速入门使用适用于测试环境的简化身份验证方法。对于生产环境,我们建议您先了解身份验证和授权,然后再选择适合您应用的访问凭据

创建一个向 Google 表格 API 发出请求的 JavaScript Web 应用。

目标

  • 设置环境。
  • 设置示例。
  • 运行示例。

前提条件

  • Google 账号

设置您的环境

如需完成本快速入门,请设置您的环境。

启用 API

在使用 Google API 之前,您需要在 Google Cloud 项目中启用它们。您可以在单个 Google Cloud 项目中启用一个或多个 API。
  • 在 Google Cloud 控制台中,启用 Google 表格 API。

    启用 API

如果您要使用新的 Google Cloud 项目完成本快速入门,请配置 OAuth 权限请求页面,并将您自己添加为测试用户。如果您已为自己的 Cloud 项目完成此步骤,请跳到下一部分。

  1. 在 Google Cloud 控制台中,依次点击“菜单”图标 > API 和服务 > OAuth 同意屏幕

    转到 OAuth 同意屏幕

  2. 为您的应用选择用户类型,然后点击创建
  3. 填写应用注册表单,然后点击保存并继续
  4. 目前,您可以跳过添加范围的步骤,点击 Save and Continue(保存并继续)。 将来,当您创建要在 Google Workspace 组织外部使用的应用时,您必须添加并验证该应用所需的授权范围。

  5. 如果您选择了外部作为用户类型,请添加测试用户:
    1. 测试用户下,点击添加用户
    2. 输入您的电子邮件地址和任何其他获得授权的测试用户,然后点击保存并继续
  6. 查看您的应用注册摘要。如要进行更改,请点击修改。如果应用注册看起来正常,请点击 Back to Dashboard

为 Web 应用授权凭据

如需在您的应用中对最终用户进行身份验证并访问用户数据,您需要创建一个或多个 OAuth 2.0 客户端 ID。客户端 ID 用于向 Google 的 OAuth 服务器标识单个应用。如果您的应用在多个平台上运行,您必须为每个平台创建单独的客户端 ID。
  1. 在 Google Cloud 控制台中,依次点击“菜单”图标 > API 和服务 > 凭据

    进入“凭据”页面

  2. 依次点击创建凭据 > OAuth 客户端 ID
  3. 点击应用类型 > Web 应用
  4. 名称字段中,输入凭据的名称。此名称只会显示在 Google Cloud 控制台中。
  5. 添加与您的应用相关的已获授权 URI:
    • 客户端应用 (JavaScript) - 在已获授权的 JavaScript 来源下,点击添加 URI。然后,输入用于浏览器请求的 URI。用于标识可供您的应用从哪些网域向 OAuth 2.0 服务器发送 API 请求。
    • 服务器端应用(Java、Python 等)- 在已获授权的重定向 URI 下方,点击添加 URI。然后,输入 OAuth 2.0 服务器可向其发送响应的端点 URI。
  6. 点击创建。系统会显示 OAuth 客户端已创建屏幕,其中显示了您的新客户端 ID 和客户端密钥。

    记下客户端 ID。客户端密钥不用于 Web 应用。

  7. 点击 OK。新创建的凭据会显示在 OAuth 2.0 客户端 ID 下方。

请记下这些凭据,因为在本快速入门中,您需要用到这些凭据。

创建 API 密钥

  1. 在 Google Cloud 控制台中,依次点击“菜单”图标 > API 和服务 > 凭据

    进入“凭据”页面

  2. 依次点击创建凭据 > API 密钥
  3. 系统随即会显示您的新 API 密钥。
    • 点击“复制”图标 以复制要在应用代码中使用的 API 密钥。您还可以在项目凭据的“API 密钥”部分找到 API 密钥。
    • 点击限制密钥,以更新高级设置并限制 API 密钥的使用。如需了解详情,请参阅应用 API 密钥限制

设置示例

  1. 在您的工作目录中,创建一个名为 index.html 的文件。
  2. index.html 文件中,粘贴以下示例代码:

    sheets/quickstart/index.html
    <!DOCTYPE html>
    <html>
      <head>
        <title>Sheets API Quickstart</title>
        <meta charset="utf-8" />
      </head>
      <body>
        <p>Sheets API Quickstart</p>
    
        <!--Add buttons to initiate auth sequence and sign out-->
        <button id="authorize_button" onclick="handleAuthClick()">Authorize</button>
        <button id="signout_button" onclick="handleSignoutClick()">Sign Out</button>
    
        <pre id="content" style="white-space: pre-wrap;"></pre>
    
        <script type="text/javascript">
          /* exported gapiLoaded */
          /* exported gisLoaded */
          /* exported handleAuthClick */
          /* exported handleSignoutClick */
    
          // TODO(developer): Set to client ID and API key from the Developer Console
          const CLIENT_ID = '<YOUR_CLIENT_ID>';
          const API_KEY = '<YOUR_API_KEY>';
    
          // Discovery doc URL for APIs used by the quickstart
          const DISCOVERY_DOC = 'https://sheets.googleapis.com/$discovery/rest?version=v4';
    
          // Authorization scopes required by the API; multiple scopes can be
          // included, separated by spaces.
          const SCOPES = 'https://www.googleapis.com/auth/spreadsheets.readonly';
    
          let tokenClient;
          let gapiInited = false;
          let gisInited = false;
    
          document.getElementById('authorize_button').style.visibility = 'hidden';
          document.getElementById('signout_button').style.visibility = 'hidden';
    
          /**
           * Callback after api.js is loaded.
           */
          function gapiLoaded() {
            gapi.load('client', initializeGapiClient);
          }
    
          /**
           * Callback after the API client is loaded. Loads the
           * discovery doc to initialize the API.
           */
          async function initializeGapiClient() {
            await gapi.client.init({
              apiKey: API_KEY,
              discoveryDocs: [DISCOVERY_DOC],
            });
            gapiInited = true;
            maybeEnableButtons();
          }
    
          /**
           * Callback after Google Identity Services are loaded.
           */
          function gisLoaded() {
            tokenClient = google.accounts.oauth2.initTokenClient({
              client_id: CLIENT_ID,
              scope: SCOPES,
              callback: '', // defined later
            });
            gisInited = true;
            maybeEnableButtons();
          }
    
          /**
           * Enables user interaction after all libraries are loaded.
           */
          function maybeEnableButtons() {
            if (gapiInited && gisInited) {
              document.getElementById('authorize_button').style.visibility = 'visible';
            }
          }
    
          /**
           *  Sign in the user upon button click.
           */
          function handleAuthClick() {
            tokenClient.callback = async (resp) => {
              if (resp.error !== undefined) {
                throw (resp);
              }
              document.getElementById('signout_button').style.visibility = 'visible';
              document.getElementById('authorize_button').innerText = 'Refresh';
              await listMajors();
            };
    
            if (gapi.client.getToken() === null) {
              // Prompt the user to select a Google Account and ask for consent to share their data
              // when establishing a new session.
              tokenClient.requestAccessToken({prompt: 'consent'});
            } else {
              // Skip display of account chooser and consent dialog for an existing session.
              tokenClient.requestAccessToken({prompt: ''});
            }
          }
    
          /**
           *  Sign out the user upon button click.
           */
          function handleSignoutClick() {
            const token = gapi.client.getToken();
            if (token !== null) {
              google.accounts.oauth2.revoke(token.access_token);
              gapi.client.setToken('');
              document.getElementById('content').innerText = '';
              document.getElementById('authorize_button').innerText = 'Authorize';
              document.getElementById('signout_button').style.visibility = 'hidden';
            }
          }
    
          /**
           * Print the names and majors of students in a sample spreadsheet:
           * https://docs.google.com/spreadsheets/d/1BxiMVs0XRA5nFMdKvBdBZjgmUUqptlbs74OgvE2upms/edit
           */
          async function listMajors() {
            let response;
            try {
              // Fetch first 10 files
              response = await gapi.client.sheets.spreadsheets.values.get({
                spreadsheetId: '1BxiMVs0XRA5nFMdKvBdBZjgmUUqptlbs74OgvE2upms',
                range: 'Class Data!A2:E',
              });
            } catch (err) {
              document.getElementById('content').innerText = err.message;
              return;
            }
            const range = response.result;
            if (!range || !range.values || range.values.length == 0) {
              document.getElementById('content').innerText = 'No values found.';
              return;
            }
            // Flatten to string to display
            const output = range.values.reduce(
                (str, row) => `${str}${row[0]}, ${row[4]}\n`,
                'Name, Major:\n');
            document.getElementById('content').innerText = output;
          }
        </script>
        <script async defer src="https://apis.google.com/js/api.js" onload="gapiLoaded()"></script>
        <script async defer src="https://accounts.google.com/gsi/client" onload="gisLoaded()"></script>
      </body>
    </html>

    替换以下内容:

运行示例

  1. 在您的工作目录中,安装 http-server 软件包:

    npm install http-server
    
  2. 在您的工作目录中,启动一个 Web 服务器:

    npx http-server -p 8000
    
  1. 在浏览器中,前往 http://localhost:8000
  2. 您会看到授权访问的提示:
    1. 如果您尚未登录 Google 帐号,请在系统提示时登录。如果您已登录多个帐号,请选择一个帐号用于授权。
    2. 点击接受

您的 JavaScript 应用运行并调用 Google Tables API。

后续步骤