APIを使ったAlteryx Gallery(Server)へのアクセスについて

「カスタマーストーリー」を支えるツール特集

#ビッグデータ

#Alteryx Server

#Alteryx

じょんすみす

2017.12.21

この記事は公開されてから1年以上経過しています。情報が古い可能性がありますので、ご注意ください。

こんにちは、小澤です。

Alteryx ServerのGalleryにアップロードされたワークフローはAPI経由での実行もできます。今回は、その方法を見ていきたいと思います。

APIからのアクセスを許可する

最初に、APIからのアクセスを許可するための設定を行います。 APIアクセスのStudioごと設定可能です。

管理者画面に入ってSubscriptionからAPIアクセスを許可したいStudioの編集画面に移ります。「API Enabled」という項目があるのでそれをYesに設定すればAPIアクセスが可能になります。

APIキー、シークレットキーを取得する

Galleryにアクセスする際にログインするのと同様、APIアクセスも誰からのアクセスなのかを認識する必要があります。 Alteryx Serverではその仕組みにOAuth1.0を利用しています。

APIキーはGalleryのユーザ設定から確認できます。

右上にある歯車のようなアイコンから「SETTINGS」を選択します。 Keysのタブを選択すると、以下のようにStudioにアクセするためのAPIキーとシークレットキーが確認できます(シークレットキーを表示するには「SHOW」を押します)。

APIからアクセスしてみる

では、APIからのアクセスをやってみましょう。今回はドキュメント内機能を使ってやってみます。

http:///gallery/api-docs/

にアクセスします。すると以下のような画面が表示されます。

上部のAPI Key, Shared Secretにアクセスキーとシークレットキーを入力するとこの画面で試しにリクエストは発行してみることができます。

試しに/v1/workflows/subscription/にアクセスしてみましょう。項目を選択すると詳細な説明が展開されます。

これは、Studio内のワークフローのリストを返すAPIになってます。

「Parameters」で必要なパラメータを選択したのち、下部にある「Try it out」を選択することでリクエストを送信することができます。

結果は以下のように確認できます。

APIでは、以下の機能が用意されているようです。

リクエストの種類	エンドポイント	機能	必須パラメータ	備考
GET	/v1/workflows/subscription/	Studio内のワークフローのリストを返す	なし	APIキーがStudio単位で発行される
GET	/v1/workflows/{appId}/questions/	Analytic Appのインターフェース上の設定項目リスト	appId	URL中の{appId}にappIdを入れる。Studio内のワークフローリストに記載されている
POST	/v1/workflows/{appId}/jobs	ワークフローを実行する	appId, values	Analytic Appの場合valuesにインターフェース上の項目値を入れる
GET	/v1/workflows/{appId}/jobs/	ワークフローの実行されたジョブリストを返す	appId
GET	/v1/jobs/{jobId}/	ジョブの詳細を取得する	jobId	jobIDはジョブリストに記載されている
GET	/v1/jobs/{jobId}/output/{outputId}/	実行されたジョブの出力ファイルを取得する	jobId, outputId
GET	/v1/{appId}/package/	ワークローを含むパッケージを返す	appId

各エンドポイントの詳細は、ドキュメントをご確認ください。

これらのAPIを利用することで、あるジョブの実行が完了したことをトリガにして別なジョブを実行させるようなことも実現できます。

APIの叩き方

さて、プログラムからAPIを叩くには少しばかりOAuth1.0の手順を踏む必要があります。上記APIリストの必須パラメータの他に以下のパラメータが必須になります。

パラメータ	入れる値
oauth_consumer_key	APIキー
oauth_signature_method	HMAC-SHA1
oauth_signature	※後述
oauth_timestamp	リクエスト発行時刻のエポック秒
oauth_nonce	適当な値
oauth_version	1.0

oauth_signatureの生成

パラメータの中で生成する必要があるものとして、oauth_signatureが出てきます。この値はHTTPのメソッド、リクエスト先、リクエストパラメータをまとめてハッシュ化する必要があります。やり方としては一般的なOAuth1.0のライブラリが利用可能ですので、ドキュメント中の「Creating your own API client」を展開した時に出てくる、サンプルのJavascriptクライアントを例に見てみましょう。

ダウンロードしたファイルのindex.htmlを開くと以下のような画面が出てきます。

API Locationには「http:///gallery/api/v1」を入れます。 API Key, API Secretはそれぞれアクセスキーとシークレットキーです。

これらを入れた状態で、「Get Subscription Workflows」を押すとワークフロー一覧が取得できます。

この時の動きとして、main.jsにある以下の処理が実行されています。

$("#getSubscriptionWorkflows").click(function(){
    gallery = new Gallery($("#apiLocation").val().trim(), $("#apiKey").val().trim(), $("#apiSecret").val().trim());
    gallery.getSubscriptionWorkflows(function(workflows){
        var listStr = "";
        var len = workflows.length;
        if (len === 0) {
            listStr = "There are no workflows in the subscription associated with the given api key";
        }
        for (var i = 0; i < len; i++){
            listStr += "<li>" + workflows[i].metaInfo.name + " - " + workflows[i].id +  "</li>";
        }
        $("#workflowList").html(listStr);
    }, function(response){
        $("#workflowList").html(response.responseJSON && response.responseJSON.message || response.statusText);
    });
});

Galleryクラス及び、getSubscriptionWorkflowsメソッドはalteryxGalleryAPI.jsで以下のように定義されています。

this.getSubscriptionWorkflows = function (success, error){
    var type = "GET",
        url = this.apiLocation + "/workflows/subscription/",
        params = buildOauthParams(this.apiKey),
    //add any user parameters before generating the signature                                                                                                                                       
        signature = generateSignature(type, url, params, this.apiSecret);
    $.extend(params, {oauth_signature: signature});
    $.ajax({
        type: type,
        url: url,
        data: params,
        success: success,
        error: error
    });
};

buildOauthParamsでOAuthに必要なパラメータをハッシュマップに入れたものを返しています。

var buildOauthParams = function(apiKey){
    return {
        oauth_consumer_key: apiKey,
        oauth_signature_method: "HMAC-SHA1",
        oauth_nonce: Math.floor(Math.random() * 1e9).toString(),
        oauth_timestamp: Math.floor(new Date().getTime()/1000).toString(),
        oauth_version: "1.0"
    };
};

これをもとに、シグニチャの作成をしているのが、generateSignature関数になります。

var generateSignature = function(httpMethod, url, parameters, secret) {
    return oauthSignature.generate(httpMethod, url, parameters, secret, null, { encodeSignature: false});
};

oauthSignatureの実態は、以下のライブラリを使用しています。