我掌握了 Looker 的 API Explorer。接下来该怎么做?

借助 Looker 的 API Explorer,用户几乎可以立即测试 API 调用,而无需编写任何代码。如果您已从 Looker Marketplace 安装 API Explorer 扩展程序,则可以点击 Looker Applications(应用)菜单中的 API Explorer,打开 API Explorer 并查看当前的 API 文档。如果您尚未安装 API Explorer 扩展程序,可以从 Looker Marketplace 的应用部分进行安装。

也许您通过使用 API Explorer 找到了动态创建 Look、更新底层查询并将其安排发送给公司内各个利益相关者的最佳工作流程。接下来,您可能会问一个常见的问题:如何在 API Explorer 之外运行这些调用或函数?以下是访问该 API 的三种常见方式:

  1. Looker 的 API 软件开发套件 (SDK)
  2. HTTP 请求
  3. 软件开发工具

本页面将引导您了解如何使用这些方法。

准备工作:身份验证和端口

无论您以何种方式访问 Looker 的 API,您首先需要两项信息:您的个人 API 身份验证信息(以客户端 ID 和客户端密钥的形式)以及 Looker 实例使用的端口号。

如需查找客户端 ID 和客户端密钥,请执行以下操作:

  • 如果您是 Looker 管理员,请在 Looker 界面中访问您感兴趣的用户的用户页面,然后前往修改密钥
  • 如果您不是 Looker 管理员,则会从 Looker 管理员那里收到客户端 ID 和客户端密钥。
关于客户端 ID 和客户端密钥,最重要的一点是不要与任何人分享这些密钥

对于托管在 Google Cloud 或 Microsoft Azure 上的 Looker 实例,以及托管在 Amazon Web Service (AWS) 上且在 2020 年 7 月 7 日或之后创建的实例,默认 Looker API 路径使用端口 443。对于 2020 年 7 月 7 日之前创建的托管在 AWS 上的 Looker 实例,默认 Looker API 路径使用端口 19999。

如果您自行托管实例,请咨询系统管理员以获取端口号。它可能是在 Looker 管理面板的 API 主机网址字段中设置的。为此,您可以前往 Looker 中的管理菜单下拉列表,然后选择 API

如需详细了解端口,请参阅 Looker API 使用入门文档页面。以下示例使用的是 API 端口 19999,但您应确认您的实例正在使用的端口。

方法 1:使用 Looker 软件开发套件 (SDK)

Looker 提供官方 Looker API 客户端 SDK,支持 PythonRubyTypescript 和 JavaScriptSwiftKotlinR。您可以在 Looker 的 sdk-examples GitHub 代码库中找到源代码和示例。

SDK 可提供工具或库,以便开发者与指定平台或应用交互。在这种情况下,Looker 的 SDK 通常包含 API。借用 Web 开发者兼作家 Kristopher Sandoval 的一个例子,“API 就像电话线,允许住宅内外进行通信。SDK 本身就是房屋及其所有内容。”他在一篇精彩的文章《API 和 SDK 有何区别?》中解释了什么是 SDK 以及它与 API 的关系。

Looker 的 SDK 包含您可能需要使用的所有 API 端点,并且以一种允许您使用所选编程语言与 Looker 无缝交互的方式进行打包。借助这些函数,您可以执行以下任务:

  • 将数据发送到 Looker
  • 从 Looker 获取数据
  • 更新 Looker 中的数据
  • 删除 Looker 中的数据
下一部分将详细讨论这些操作之间的差异。

以下示例展示了如何使用 Python SDK 更新用户:

  1. 使用 looker_sdk.init 初始化会话。
  2. 使用 sdk.update_user 更新用户。您需要传递 user_id 以指定要更新的用户。
  3. 使用 models.WriteUser 指定您要如何更新用户。

    #### Initialize API/SDK for more info go here: https://pypi.org/project/looker-sdk
    from looker_sdk import methods40, models
    sdk = looker_sdk.init40()
    me = sdk.me()
    # print(me)
    new_friend = sdk.update_user(user_id=29,
    body=models.WriteUser(first_name="newnew", last_name="new_again"))
    print(new_friend)
  

在使用我们的某个 SDK 时,如果您使用 Visual Studio Code 等 IDE,然后按住 Command 键点击(在 Visual Studio Code 的默认设置中为 F12),再选择 go to definitions,您就可以看到所有方法以及这些方法接受或返回的所有参数。或者,您可以在 SDK GitHub 代码库中查看它们 - 查找方法和模型文件。

方法 2:使用 curl 或 requests 库发送 HTTP 请求

如果您不想编写脚本,也不想花数月或数年时间学习新的编程语言,该怎么办?在这种情况下,您可以使用 curl 发出 HTTP 请求,以利用 Looker 的 API。

HTTP 请求会向目的地(可以是服务器、手机,甚至是智能电视)发送消息。HTTP 请求有几种不同的类型。您如何将这些请求与 Looker 的 API 搭配使用取决于您在 API 调用中传递的方法的性质。有些方法会为您提供数据,有些方法会将数据发送到 Looker,有些方法会更新数据,还有些方法会从 Looker 中删除或移除数据。

操作 方法
创建 POST
读取 GET
更新 PUT
删除 DELETE

让我们开始打冰壶吧。如需了解一些背景信息,请参阅 Zendesk 提供的精彩教程:安装和使用 c网址

如需开始向 Looker API 发出 HTTP 调用,您需要做的第一件事是使用您的客户端 ID 和客户端密钥调用 Looker API 的 login 端点。这会创建访问令牌。然后,您获取此访问令牌,并在每次调用时传递该令牌。访问令牌可确保调用来自已获授权的用户。

此页面使用了一些符号来指示您应将代码示例中的文本替换为您的信息。Looker 托管型实例网址采用 https://<hostname>.<subdomain>.<domain>.com 格式;如果您在本页面的示例中看到此表示法,请将 <hostname>.<subdomain>.<domain>.com 部分替换为您的 Looker 实例网址。此外,我们使用 <value> 符号来指示您应在代码示例中输入适当的值,替换 <value>。例如,在以下代码中,将显示 client_id=<value>&client_secret=<value> 的位置,将第一个 <value> 替换为您的 client_id,并将第二个 <value> 替换为您的 client_secret

以下是用于获取访问令牌的 curl 命令:

  curl -d "client_id=<value>&client_secret=<value>" https://<hostname>.<subdomain>.<domain>.com:19999/login
  

回答如下:

  {"access_token":"ABCDEFGHIJLMNOP1234","token_type":"Bearer","expires_in":3600}
  

收到令牌表示 Looker 识别了您的 API 凭据。系统会返回令牌以及一个 expires_in 值,用于指明令牌的有效时长。通常约为 60 分钟(3,600 秒)。

现在您已拥有访问令牌,可以开始进行调用了。所有端点均按 API 版本列在 Looker API 4.0 参考文档中。请注意,Looker 的社区网站 是一个很好的资源,您可以在其中向其他 Looker 用户询问有关如何利用 API 的问题、了解最佳实践,或者与其他用户分享您在使用 API 方面取得的成功。

假设您要创建新用户。为此,请执行以下操作:

  1. 编写一个 curl POST 请求,将您的令牌传递给 Looker,以告知 Looker 您已获得授权。
  2. 添加一个正文(在本例中以 JSON 格式设置),告知 Looker 您希望新用户拥有哪些属性。(有些字段是 API 调用的必需字段,因此请参阅 Looker API 4.0 参考文档。)
  3. 以要使用的端点(在本例中为 users)结束 curl 表示法。

  curl -H "Authorization: token <value>
  " -H "Content-Type: application/json" -d "{\"first_name\": \"<value>\",\"last_name\": \"<value>\", \"email\":\"<value>\"}" https://<hostname>.<subdomain>.<domain>.com:19999/api/4.0/users

-H 表示标题,-d 表示数据。如需详细了解 curl 命令,请前往此 GitHub gist

您刚刚创建了一个用户,其名字、姓氏和电子邮件地址的值与您之前输入的值相同。

如果您想在脚本中编写此内容,这样就无需在每次想完成此工作流程时都写出这些命令,该怎么做?您可以使用编程语言和库,例如 Python 的 requests

例如,以下脚本使用 requests 库通过 Look ID(looks 调用中的 <value>)获取 Look,应用新过滤条件,然后将结果下载为 CSV 文件:

  import requests
  ID = '<value>'
  SECRET = '<value>'
  PARAMS = {'client_id':<value>,
            'client_secret': <value>}
  URL = "https://<hostname>.<subdomain>.<domain>.com:19999/api/4.0/login"
  r = requests.post(url = <value>, params = <value>, verify=False)
  data = r.json()
  token = data['access_token']
  print(token)
  headers = {'Authorization': "Bearer " + token}
  print(headers)
  look_url = "https://<hostname>.<subdomain>.<domain>.com:19999/api/4.0/looks/<value>"
  look = requests.get(look_url, headers=headers, verify=False)
  json = look.json()
  query = json['query']
  ### ADD MODEL HERE
  ### ADD FILTER
  body = {
      "model":"<value>",
      "view":query['view'],
      "fields":query['fields'],
      "filters":{<value>}
  }
  print(body)
  run_inline = "https://<hostname>.<subdomain>.<domain>.com:19999/api/4.0/queries/run/csv"
  run_query = requests.post(run_inline, headers = headers, json=body, verify=False)
  print(run_query._content)
  print(run_query.url)

选项 3:软件开发工具

借助 PostmanPaw 等工具,用户可以通过图形界面 (GUI) 互动或利用 API 端点。对于软件开发工具,也适用与 HTTP 请求相同的流程。第一步是使用客户端密钥和客户端 ID 登录。然后,将访问令牌存储为不记名令牌,以授权后续的 API 调用,如下面的 Postman 示例所示。

Postman GUI,其中填充了 Looker POST 网址、客户端密钥和客户端 ID。

借助 Postman 或其他软件开发工具(如 Paw),您可以在其界面中指定授权、正文、参数和标头,然后生成请求。当您点击发送时,它们也会执行相应端点。

加油!(但请务必小心)

现在,您可以通过 SDK、HTTP 请求和软件开发工具使用 Looker 的 API,快去试试吧!不过,请注意,虽然使用 API 可以帮助您自动执行一些流程,例如在用户离职后创建或重新分配日程,但 API 使用不当可能会损坏实例。

以下是一些需要注意的常规事项:

  • 在修改权限或删除用户时(尤其是批量操作时),请务必谨慎。您可能会删除或锁定许多用户(包括管理员),而此类操作无法轻易撤消。
  • API 调用会增加实例使用量,因此请尝试在非高峰时段安排 API 调用,以获得最佳性能。
  • 每个实例服务器都有打开文件数量限制,因此不负责任地使用 API 可能会导致实例崩溃。
  • 在将工作流和函数添加到生产环境之前,先小规模测试一下。
  • 切勿分享您的 API 凭据,也不要将其留在其他用户可以访问的文件中。

如果您有任何问题或想分享一个好点子,请访问 Looker 社区。如果您认为我们可以在哪些方面进行改进,或者希望我们在文档中添加哪些其他示例,欢迎随时告诉我们。