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

借助 Looker 的 API Explorer,用户无需编写任何代码,即可几乎立即测试 API 调用。如果您已从 Looker Marketplace 安装了 API Explorer 扩展程序,则可以点击 Looker 应用菜单中的 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 实例,以及在 2020 年 7 月 7 日当天或之后创建且托管在 Amazon Web Services (AWS) 上的实例,默认的 Looker API 路径使用端口 443。对于在 2020 年 7 月 7 日之前托管在 AWS 上的 Looker 实例,默认的 Looker API 路径使用端口 19999。

如果您托管自己的实例,请咨询系统管理员了解端口号。您可以在 Looker 的管理控制台的 API 主机网址字段中进行设置。如需查看此信息,请前往 Looker 中的管理菜单下拉菜单,然后选择 API

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

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

Looker 提供 PythonRubyTypescript 和 JavaScriptSwiftKotlinR 版本的官方 Looker API 客户端 SDK。您可以在 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 并按住 ⌘ 键点击(在 Visual Studio Code 的默认设置中为 F12),然后选择转到定义,您可以查看所有方法以及这些方法接受或返回的所有参数。或者,您也可以在 SDK GitHub 代码库中查看这些文件,具体方法是查找方法和模型文件。

方法 2:使用 curl 或请求库发出 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 秒)。

现在,您已经有了访问令牌,可以随意进行任何调用了。Looker API 4.0 参考文档中按 API 版本列出了所有端点。请注意,Looker 的社区网站 是一个很好的资源,您可以在此网站上向其他 Looker 用户询问他们如何利用 API、学习最佳实践,或与其他用户分享您在使用 API 时取得的成就。

假设您要创建新用户。具体操作步骤如下:

  1. 编写一个 curl POST 请求,传递您的令牌,以告知 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 库根据外观 ID(looks 调用中的 <value>)获取外观,应用新过滤条件,然后将结果下载为 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 端点互动或利用 API 端点。软件开发工具适用与 HTTP 请求相同的流程。第 1 步是使用客户端密钥和客户端 ID 登录。然后,将访问令牌存储为不记名令牌,以授权后续的 API 调用,如 Postman 中所示。

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

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

加油!(但请务必小心)

现在,您可以通过 SDK、HTTP 请求和软件开发工具使用 Looker 的 API,接下来就开始测试吧!不过,请注意,虽然使用该 API 有助于自动执行在用户离开贵公司后创建或重新分配时间表等流程,但不当使用该 API 可能会损坏实例。

一些常规注意事项:

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

如果您有任何问题或想分享有趣的想法,请访问 Looker 社区。如果您认为我们可以改进的地方,或者您希望在我们的文档中添加其他示例,欢迎随时告诉我们。