Looker API Getting Started

はじめに

この記事ではLooker APIの使い方について説明します。
APIのバージョンは4.0です。

Looker APIとは

Looker APIは、Lookerの機能を外部から利用するためのAPIです。
Looker APIを使うことで、Lookerの機能を外部アプリケーションから利用できます。

APIのエンドポイントを知る

APIを使うためには、まずAPIのエンドポイントを知る必要があります。
APIのエンドポイントは以下の通りです。

• エンドポイント: https://インスタンス名.looker.com:19999/api/4.0/

インスタンス名には、Lookerのインスタンス名を指定します。インスタンス名はユーザーによって異なります。
確認方法としては、Lookerのログイン画面にアクセスすることで確認できます。

APIの使い方

APIを使うための手順は以下の通りです。

1. APIのエンドポイントにアクセスする
2. APIの認証を行う
3. 認証トークンを取得する
4. 認証トークンを使ってAPIにアクセスする
5. APIのレスポンスを受け取る

他のサービス（たとえば、SaaSなど）でAPIを利用したことがある場合はイメージがつかみやすいかもしれません。
なお、APIの認証にはAPIキーを使いますので管理者に問い合わせて取得してください。

どんなことができるのか

Looker APIを使うことで、以下のようなことに対応できます。

• Lookの作成
• ダッシュボードの作成
• ダッシュボードの共有（PDFとして配信するためのスケジューリングなど）
• アラートの設定
• クエリの実行

Looker API Reference

他にもさまざまなことが実行できますが、分析でよくつかうものに絞ると上記のようなものが主になります。
LookMLに知見のある方であれば、LookのLookMLをAPI経由で取得することも可能です。

実装例

では、実際にAPIを使ってみましょう。今回はGoogle Apps Script（GAS）を使ってAPIを実行します。

Looker APIを実行するには以下の2工程を踏む必要があります。

1. APIキーを使って認証トークンを取得する
2. 項番1で取得した認証トークンを使ってリクエストを発行する

項番2のリクエストを発行するでは認証トークンの他にAPIに必要なpayloadをつけてリクエストを実行する必要があります。
説明だけ聞いていてもわかにくいと思うので実際に実行してみましょう。

APIキーを使って認証トークンを取得する

認証はAPIキー（client_id, client_secret）で認証トークンを取得することで実装できます。
GASでは｀UrlFetchApp`を使ってAPIを実行できます。

リクエストする際のパス：/login
メソッド:POST
content-type: “application/x-www-form-urlencoded”
payload: APIキーのclient_idとclient_secret

2つの方法がありますが、クエリパラメータを使わない方法が良いです。

function login() {
 try{
  var post = {
    method: 'post',
    contentType: 'application/x-www-form-urlencoded',
    payload: "client_id="+CLIENT_ID+"&client_secret="+CLIENT_SECRET
  };
  var response = UrlFetchApp.fetch(BASE_URL + "/login", post);
  return JSON.parse(response.getContentText()).access_token;
 } catch(err) {
  return "Could not login to Looker. " + err
 }
}

以下、クエリパラメータを使う方法です。

function login() {
 try{
  var post = {
    method: 'post'
    contentType: 'application/x-www-form-urlencoded',
  };
  var response = UrlFetchApp.fetch(BASE_URL + "/login?client_id=" + CLIENT_ID + "&client_secret=" + CLIENT_SECRET, post);
  return JSON.parse(response.getContentText()).access_token;
 } catch(err) {
  return "Could not login to Looker. " + err
 }
}

SQL Runnerを実行する

SQL Runnerを使ってクエリを実行することができます。
リクエストする際のパス：/sql_queries
メソッド:POST
content-type: “Application/json”

ヘッダー：

"headers": {
    "Authorization": "token {認証トークン}"
}

※{認証トークン}は、APIキーを使って取得した認証トークンです。login()関数で取得したトークンを使います。

payload:
モデル名とSQLを指定します。

{
    "model_name":"{モデル名}",
    "sql":"{SQL}"
}

以下は、SQL Runnerを使ってクエリを実行する例です。
引数をSQLとして受け取り、SQL Runnerにリクエストを送信します。

function LOOKER_CREATE_SQLRUNNER_QUERY(SQL){
  try {
    var payload = {
      "model_name":'model_name',
      "sql":SQL
    }
    var options = {
      "method": "post",
      "content-type" : "Application/json",
      "headers": {
        "Authorization": "token " + login()
      },
      "payload": JSON.stringify(payload)
    };

    // get request for the look
    var response = UrlFetchApp.fetch(BASE_URL + "/sql_queries", options);

    let resContent = JSON.parse(response.getContentText());
    return resContent["slug"];

  } catch (err) {
    console.log("ERROR");
    return "Uh oh! Something went wrong. Check your API credentials and if you're passing the correct parameters and that your Look exists!";
  }
}

戻り値：クエリのslugが返されます。ここでいうslugとは、クエリのIDのようなものです。

参考 – create_sql_query

slugからクエリを実行する

リクエストする際のパス：/sql_queries/{slug}/run/{result_format}
{slug}はクエリのID、{result_format}は実行結果をどういうフォーマットで取得するかを指定します。

メソッド:GET
content-type: “Application/json”

ヘッダー：

"headers": {
    "Authorization": "token {認証トークン}"
}

※{認証トークン}は、APIキーを使って取得した認証トークンです。login()関数で取得したトークンを使います。

function LOOKER_RUN_QUERY(slug){
  try {
    var options = {
      "method": "post",
      "content-type" : "Application/json",
      "headers": {
        "Authorization": "token {認証トークン}"
      }
    };

    var response = UrlFetchApp.fetch(BASE_URL + "/sql_queries/" + slug + "/run/csv", options);
    return Utilities.parseCsv(response.getContentText());

  } catch (err) {
    console.log("ERROR");
    return "Uh oh! Something went wrong. Check your API credentials and if you're passing the correct parameters and that your Look exists!";
  }
}

参考 – Run Query

Lookを実行する

リクエストする際のパス：/looks/{LookのID}/run/{result_format}
{lookのID}はLookのID、{result_format}は実行結果をどういうフォーマットで取得するかを指定します。

メソッド:GET
content-type: “Application/json”

ヘッダー：

"headers": {
    "Authorization": "token {認証トークン}"
}

※{認証トークン}は、APIキーを使って取得した認証トークンです。login()関数で取得したトークンを使います。

function LOOKER_RUN_LOOK(id, opt_format, opt_limit) {
  try {
    var options = {
      "method": "get",
      "headers": {
        "Authorization": "token " + login()
      }
    };

    // set formatting to either csv or the raw sql query since sheets is limited
    var formatting;
    // convert param
    switch (opt_format) {
      case 1:
      formatting = "csv";
      break;

      case 2:
      formatting = "sql";
      break;

      case 3:
      formatting = "txt";
      break;

      case 4:
      formatting = "md";
      break;

      default:
      formatting = "csv";
    }

    // set a custom limit
    var limit;
    if(opt_limit) {
      limit = opt_limit;
    // else use the 5k default
    } else if (opt_limit == -1) {
      limit = -1;
    } else {
      limit = 500;
    }

    // get request for the look
    var response = UrlFetchApp.fetch(BASE_URL + "/looks/" + id + "/run/" + formatting + "?limit=" + limit+"&apply_formatting=true", options);

    // if it's csv, fill it in the cells, if it's the query, use one cell only, if not specified, throw error
    if (opt_format == 1) {
      return Utilities.parseCsv(response.getContentText());
    } else if (opt_format == 2){
      return response.getContentText();
    }
    else {
      return Utilities.parseCsv(response.getContentText());
    }
  } catch (err) {
    return "Uh oh! Something went wrong. Check your API credentials and if you're passing the correct parameters and that your Look exists!";
  }
}

まとめ

Looker APIでは他にもさまざまなことが可能です。
また、今回は紹介しませんでしたが、Looker APIをプレイグランド的にハンズオンできるAPI Explorerというものがあります。

「ちょっと動かしてみたい」、「なかなかAPIが動作してくれない」などのお試しにも利用できますのでぜひ、利用してみてください。