📘

Synapse Analytics REST API でパイプラインを起動、監視する方法

2022/05/02に公開

Synapse Analytics のパイプライン起動や監視を REST API で行う方法について記載します。Azure Data Factory の API にも同等の機能がありますが、使い方が異なることにご注意ください。

Azure Active Directory でアプリケーションを登録

クライアントが Synapse Analytics API にアクセスできるようにするためには、Azure Active Directory にアプリケーションを登録し、クライアントシークレットを設定しておく必要があります。登録及び設定は、以下のドキュメントの

  • アプリケーションを登録する
  • クライアントシークレットの追加

の手順に沿って行ってください。今回の手順ではリダイレクト URL は使用しないため、設定する必要はありません。

https://docs.microsoft.com/ja-jp/azure/active-directory/develop/quickstart-register-app

テナント IDアプリケーション IDシークレット値は後で使用するので、控えておいてください。

Synapse RBAC の設定

Azure AD アプリケーションを使用してパイプラインの操作を行うためには、アプリケーションに対して以下の Synapse RBAC ロールを割り当ててください。

  • Synapse ユーザー
  • Synapse 情報ユーザー
  • Synapse 成果物ユーザー

その他の操作を行う RREST API を使用する場合は、必要なロールを追加で割り当ててください。

Azure Active Directory からアクセストークンの取得

Azure Active Directory からアクセストークンを取得するために、以下の REST API をコールします。

https://login.microsoftonline.com/<テナントID>/oauth2/token

リクエストメソッド:POST
ヘッダー:
Content-Type:application/x-www-form-urlencoded
本文:
client_id=<アプリケーションID>&client_secret=<シークレット値>&grant_type=client_credentials&resource=https://dev.azuresynapse.net/

以下のようなレスポンスが得られるので、access_token の値をアクセストークン値として控えておきます。

{
    "token_type": "Bearer",
    "expires_in": "3599",
    "ext_expires_in": "3599",
    "expires_on": "1649843102",
    "not_before": "1649839202",
    "resource": "https://dev.azuresynapse.net/",
    "access_token": "xxx"
}

Synapse パイプラインの起動

以下の REST API をコールしてパイプラインを起動します。

https://<ワークスペース名>.dev.azuresynapse.net/pipelines/<パイプライン名>/createRun?api-version=2020-12-01

リクエストメソッド:POST
ヘッダー:
Authorization:Bearer <アクセストークン値>
Content-Type:application/json
本文:(パイプライン起動時に指定するパラメータがある場合は指定)

以下のようなレスポンスが得られるので、runIdの値をランIDとして控えておきます。

{
    "runId": "xxx"
}

REST API のリクエスト/レスポンスの詳細については、以下のドキュメントを参照してください。
https://docs.microsoft.com/ja-jp/rest/api/synapse/data-plane/pipeline/create-pipeline-run

起動したパイプラインの監視

以下の REST API をコールしてパイプラインを監視します。

https://<ワークスペース名>.dev.azuresynapse.net/pipelines/<パイプライン名>/pipelineruns/<ランId>/queryActivityruns?api-version=api-version=2020-12-01

リクエストメソッド:POST
ヘッダー:
Authorization:Bearer <アクセストークン値>
Content-Type:application/json
本文:(絞り込み条件を指定する場合は指定)

パイプラインの実行状況を JSON 形式で取得できます。

REST API のリクエスト/レスポンスの詳細については、以下のドキュメントを参照してください。
https://docs.microsoft.com/ja-jp/rest/api/synapse/data-plane/pipeline-run/query-activity-runs

Discussion