Tableau OnlineのAPI呼び出し

# 概要
- TableauのREST APIを使った記録。
- やりたかったことは「APIでのフローの実行」であった。しかし最終的には、**Data Management add-on という製品を契約しないと「APIでのフローの実行」はできない**という結論に至った。
    - [Error "Tableau Prep Conductor must be enabled on your site settings to schedule flows"](https://kb.tableau.com/articles/Issue/error-tableau-prep-conductor-must-be-enabled-on-your-site-settings-to-schedule-flows)
    - ちなみにData Management add-onの費用は、サイト内で契約している総アカウント費用の何％だかなので、大きなプロジェクトだとかなり選択しづらい。できれば使いたくないというモチベーションで調査した。
- ここでは上記の目的の調査のために、接続、プロジェクト一覧、フロー一覧の取得等はできたので、いつか何かで使えることがあるかもしれない。誰かの役に立つかもしれない。そのための知見を残しておく。
## 参考リンク
- [Tableau REST API Help](https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api.htm)


# APIの呼び出しの説明

## 全体
- 下記の処理を試行した。
    - サインイン
    - プロジェクト一覧を取得
    - フロー一覧を取得
    - フローを実行（できなかった）

## サインイン

### 概要
- 呼び出し方
    - `POST https://{{SERVER_NAME}}/api/{{API_VERSION}}/auth/signin`
    - [Authentication Methods](https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_ref_authentication.htm)
- SERVER_NAMEは、Onlineでログインした後のURLのドメイン。（今回はprod-apnortheast-a.online.tableau.comだった）
    - ヘルプのどこかに、`10ax.online.tableau.com`とか地域を示すサーバーであるようなことが書いてあった。
- API_VERSIONは、3.17。2022/11/12時点で最新。
    - ちなみに、`3.17`のドットは小数点ではなく区切り文字で、ドット以下の２桁の17(seventeen)。10の前は9。
- contentUrl（bodyで指定している）は、Onlineのsiteの後の区画で定義されている意味のある名前。[REST APIのチュートリアル](https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_get_started_tutorial_part_1.htm)では、`MarketingTeam`と書いてあった。
- ユーザー名とパスワードのログインではなく、Personal Access Tokenでのログイン。
    - [Signing In and Out (Authentication)](https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_concepts_auth.htm)
    - ログインID・パスワードは使わず、処理用のIDを使って一時的なセッション情報のような情報（トークン）を得て、サインイン後の処理はそのトークンを使って接続する。
    - ↓でもうちょっと詳しく説明してる。
- サインインに成功したら、戻り値のXMLを解析して、トークンとSITE_IDを環境変数に設定している。
    - Postmanでは、Testsというタブで取得後の処理をJavaScriptで書けるので、そこで結果を読んで環境変数に設定した。そうすることで、サインインした後に次のAPIを呼び出すときに、環境変数で利用できる。
        - 格納用の変数は、事前に空で定義しておく。
        - PostmanでJavaScriptのコンソールも見れるので、例えば下記の`data`がどうなっているか知りたいときは、`console.log(data);`で、中身を確認できる。
    ```JavaScript:Testsタブ
    var data = xml2Json(responseBody);
    //console.log(data);

    postman.setEnvironmentVariable("CREDENTIALS_TOKEN", data.tsResponse.credentials.$.token);
    postman.setEnvironmentVariable("SITE_ID", data.tsResponse.credentials.site.$.id);
    ```

### Personal Access Token(PAT)の取得方法、注意点など
- 下記の手順で、`personalAccessTokenName`と`personalAccessTokenSecret`を取得する。
    1. 右上の自分のアイコンから毎アカウントの設定
    2. 設定タブ
    3. 個人用アクセストークン
    4. 適当な名前で新しいトークンの作成
- Nameは自分で設定した文字列で、token secretは、「oKPkF2LGRG66tht+Ht8OKA==:VNDncTa4TdrDbnbTQoTcO0b6dhdbvEQV」といった、自動的に生成されたパスワードのような長い文字列。
- 一度発行すると、Tableauの画面でも再確認はできず、新しい名前で取得するしかない。
- ここで取得したトークンは、ユーザーに依存するため、システム化して使用する場合には、（おそらく）そのユーザーアカウントがずっと生きていないといけない。したがって、システム用のアカウントを作成する等の工夫をしないといけないかもしれない。


## プロジェクト一覧を取得
### 概要
- 呼び出し方
    - `GET https://{{SERVER_NAME}}/api/{{API_VERSION}}/sites/{{SITE_ID}}/projects`
    - [Projects Methods #Query Projects](https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_ref_projects.htm#query_projects)
- サインイン時に取得した、トークンをヘッダーの`X-Tableau-Auth`に設定し、サイトIDはURIの一部で使用している。
- この処理は、目的に対しては必要ではなかったが、サインインした結果を確認するために呼び出してみた。


## フロー一覧を取得
### 概要
- 呼び出し方
    - `GET https://{{SERVER_NAME}}/api/{{API_VERSION}}/sites/{{SITE_ID}}/flows`
    - [Flow Methods #Query Flows for a Site](https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_ref_flow.htm#query_flows_for_site)
- 後処理で、JavaScriptを使って、目的のフローを探してIDを環境変数へ設定している。
```JavaScript:Testsタブ
// 特定のフローのIDを抽出
var data = xml2Json(responseBody);
//console.log(data);

for (var i=0; i<data.tsResponse.flows.flow.length; i++){
    if (data.tsResponse.flows.flow[i].$.name=="フロー名１２３４"){
        postman.setEnvironmentVariable(
            "FLOW_ID",
            data.tsResponse.flows.flow[i].$.id
        );
    }
}
```

## フローを実行
### 概要
- 呼び出し方
    - `POST https://{{SERVER_NAME}}/api/{{API_VERSION}}/sites/{{SITE_ID}}/flows/{{FLOW_ID}}/run`
    - [Flow Methods #Run Flow Now](https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_ref_flow.htm#run_flow_now)
        - フローを今すぐ実行
- 呼び出した結果、下記が返ってきた。
    ```XML:Response
    <?xml version='1.0' encoding='UTF-8'?>
    <tsResponse xmlns="http://tableau.com/api" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://tableau.com/api https://help.tableau.com/samples/en-us/rest_api/ts-api_3_17.xsd">
        <error code="403004">
            <summary>Forbidden</summary>
            <detail>Tableau Prep Conductor must be enabled on your site settings to schedule flows. Contact your administrator.</detail>
        </error>
    </tsResponse>
    ```
    - 説明ページが下記
        - [Error "Tableau Prep Conductor must be enabled on your site settings to schedule flows"](https://kb.tableau.com/articles/Issue/error-tableau-prep-conductor-must-be-enabled-on-your-site-settings-to-schedule-flows)
    - UIを使って手動で実行するか、**Management add-on**を使って"フローのスケジュール設定"が必要。

# ツールの説明
- REST APIの呼び出しツールは、下記を試した。（いろいろなエラーが出て、原因がわからなかったので、ツールも試行錯誤した。）
    - WindowsのPowerShellからのcurl
    - VSCodeのREST Client
    - Postman
- 一連の処理を行うなら、Pythonで実装するのがよいかも。

## PowerShellを使うときの注意
- curl.exeとして呼び出す必要あり。
    - 参考：[Windows Powershellでcurlを使うときの注意点](https://zenn.dev/yu1low/articles/f559f35c7087ef)

## VSCodeを使うときの注意
- VSCodeの機能拡張の REST Client を使った。簡単なので。
- 呼び出しのときのスペースやダブルクォーテーションはそのまま使用されるので注意。
    - 下記が正解
        ```
        GET https://prod-apnortheast-a.online.tableau.com/api/3.17/sites/abc1234abc1234abc1234/projects
        X-Tableau-Auth:tokenhogehoge
        ```
    - 下記はいずれもNG
        - トークンの一部としてスペースが含まれる
        ```
        X-Tableau-Auth: tokenhogehoge
        ```
        - トークンの一部としてダブルクォーテーションが含まれる
        ```
        X-Tableau-Auth:"tokenhogehoge"
        ```
- １つのファイルに複数の呼び出しを書く場合は、`###`の行を挟む。