この記事は公開されてから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の実態は、以下のライブラリを使用しています。
こちらは一般的なOAuth1.0に対応したライブラリとなりますので、他の言語でもライブラリの利用で対応可能でしょう。
最後に得られたシグニチャをパラメータに追加して、リクエストを投げています。
おわりに
今回は、Alteryx ServerのGallery APIについて解説しました。
APIを使えば他のシステムと連携してワークフローを実行したり、特定の時間以外の要素をトリガとしたタイミングでのワークフロー実行が可能になります。 そういったことをしたいという方はぜひ参考にしていただければと思います。
Alteryxの導入なら、クラスメソッドにおまかせください
日本初のAlteryxビジネスパートナーであるクラスメソッドが、Alteryxの導入から活用方法までサポートします。14日間の無料トライアルも実施中ですので、お気軽にご相談ください。