REST API を使用した非同期更新

REST 呼び出しをサポートしているプログラミング言語を使用することで、クエリのスケールアウトのための読み取り専用レプリカの同期を含む、Azure Analysis Services 表形式モデルでの非同期データ更新操作を実行できます。

データ更新操作は、データボリュームや、パーティションを使用した最適化のレベルなどの多くの要因に応じて、ある程度時間がかかる可能性があります。従来これらの操作は、TOM (表形式オブジェクトモデル)、PowerShell コマンドレット、または TMSL (表形式モデルスクリプト言語) などの既存の方法を使用して呼び出されていました。しかし、多くの場合、これらの方法は信頼性が低く実行時間が長い HTTP 接続を必要とします。

Azure Analysis Services 用の REST API なら、データ更新操作を非同期で実行できます。 REST API を使用すれば、クライアントアプリケーションからの実行時間の長い HTTP 接続は不要になります。他にも、自動の再試行やバッチ処理されたコミットなどの信頼性を高める組み込み機能もあります。

基準URL

ベース URL は、次の形式に従います。

https://<rollout>.asazure.windows.net/servers/<serverName>/models/<resource>/

たとえば、米国西部の Azure リージョンにある myserver という名前のサーバーの、AdventureWorks という名前のモデルの場合、サーバー名は次のようになります。

asazure://westus.asazure.windows.net/myserver

このサーバー名のベース URL は次のようになります。

https://westus.asazure.windows.net/servers/myserver/models/AdventureWorks/

このベース URL を使用すると、次のパラメーターに基づいたリソースと操作を追加できます。

非同期更新ロジックを示すダイアグラム。

末尾が s ならコレクション。
末尾が () なら関数。
その他はリソース/オブジェクト。

たとえば、次のように Refreshes コレクションに対して POST 動詞を使用すれば、更新操作を実行できます。

https://westus.asazure.windows.net/servers/myserver/models/AdventureWorks/refreshes

認証

すべての呼び出しは、Authorization ヘッダー内の有効な Microsoft Entra ID (OAuth 2) トークンで認証する必要があり、次の要件を満たす必要があります。

そのトークンはユーザートークンまたはアプリケーションサービスプリンシパルのどちらかである必要があります。
トークンは対象ユーザーを厳密に https://*.asazure.windows.net に設定している必要があります。 * はプレースホルダーでもワイルドカードでもないことに注意してください。対象ユーザーは * 文字をサブドメインとして持っている必要があります。 https://customersubdomain.asazure.windows.net などのカスタム対象ユーザーはサポートされていません。無効な対象ユーザーを指定すると、認証エラーが発生します。
そのユーザーまたはアプリケーションは、要求された呼び出しを実行するために、サーバーまたはモデルに対する十分なアクセス許可を与えられている必要があります。そのアクセス許可のレベルは、モデル、またはサーバー上の管理者グループ内のロールによって決定されます。

重要

現時点では、サーバー管理者ロールのアクセス許可が必要です。

POST /refreshes

更新操作を実行するには、/refreshes コレクションに対して POST 動詞を使用して、新しい更新項目をコレクションに追加します。応答内の Location ヘッダーには、更新 ID が含まれています。このクライアントアプリケーションは非同期であるため、接続を切断して、必要に応じてあとで状態を確認できます。

1 つのモデルに対して一度に 1 回の更新操作のみ可能です。現在実行中の更新操作がある場合に別の更新操作が送信されると、409 競合 HTTP 状態コードが返されます。

本文は次の文に似たものになっているはずです。

{
    "Type": "Full",
    "CommitMode": "transactional",
    "MaxParallelism": 2,
    "RetryCount": 2,
    "Objects": [
        {
            "table": "DimCustomer",
            "partition": "DimCustomer"
        },
        {
            "table": "DimDate"
        }
    ]
}

パラメーター

このパラメーターが指定されていない場合は、既定値が適用されます。

名前	タイプ	説明	既定値
`Type`	Enum	実行する処理の種類。これらの型は、TMSL の Refresh コマンドの種類 (`full`、`clearValues`、`calculate`、`dataOnly`、`automatic`、および `defragment`) に合わせられます。 `add` 型はサポートされていません。	`automatic`
`CommitMode`	Enum	オブジェクトがバッチでコミットされるか、操作全体が完了したときにのみコミットされるかを決定します。モードには `transactional`、`partialBatch` があります。	`transactional`
`MaxParallelism`	整数	この値は、複数の処理コマンドを並列に実行するスレッドの最大数を決定します。この値は、TMSL の Sequence コマンドやその他のメソッドで設定できる MaxParallelism プロパティと一致します。	10
`RetryCount`	整数	操作を失敗にするまでの再試行回数を示します。	0
`Objects`	配列	処理されるオブジェクトの配列です。各オブジェクトには、テーブル全体を処理する時には "table" が、またはパーティションを処理する時には "table" と "partition" が含まれます。オブジェクトが指定されていない場合は、モデル全体が更新されます。	モデル全体を処理

partialBatch に CommitMode を指定すると、読み込みに何時間もかかる可能性がある大規模なデータセットを最初に読み込むときに便利です。 1 つまたは複数のバッチのコミットに成功したあとに更新操作が失敗すると、コミットに成功したバッチはコミットされたままになります (コミットに成功したバッチはロールバックされません)。

注

書き込み時、バッチサイズは MaxParallelism の値になりますが、この値は変わる可能性があります。

状態の値

状態の値	説明
`notStarted`	操作はまだ開始されていません。
`inProgress`	操作は実行中です。
`timedOut`	ユーザー指定のタイムアウトに基づいて、操作がタイムアウトしました。
`cancelled`	操作はユーザーまたはシステムによって取り消されました。
`failed`	操作に失敗しました。
`succeeded`	操作が成功しました。

GET /refreshes/<refreshId>

更新操作の状態を確認するには、更新 ID に対して GET 動詞を使用します。応答の本文の例を次に示します。操作が進行中の場合、状態として inProgress が返されます。

{
    "startTime": "2017-12-07T02:06:57.1838734Z",
    "endTime": "2017-12-07T02:07:00.4929675Z",
    "type": "full",
    "status": "succeeded",
    "currentRefreshType": "full",
    "objects": [
        {
            "table": "DimCustomer",
            "partition": "DimCustomer",
            "status": "succeeded"
        },
        {
            "table": "DimDate",
            "partition": "DimDate",
            "status": "succeeded"
        }
    ]
}

GET /refreshes

モデルの更新操作の履歴リストを取得するには、/refreshes コレクションに対して GET 動詞を使用します。応答の本文の例を次に示します。

注

書き込み時、直近の 30 日間の更新操作が保存され返されますが、この日数は変わる可能性があります。

[
    {
        "refreshId": "1344a272-7893-4afa-a4b3-3fb87222fdac",
        "startTime": "2017-12-07T02:06:57.1838734Z",
        "endTime": "2017-12-07T02:07:00.4929675Z",
        "status": "succeeded"
    },
    {
        "refreshId": "474fc5a0-3d69-4c5d-adb4-8a846fa5580b",
        "startTime": "2017-12-07T01:05:54.157324Z",
        "endTime": "2017-12-07T01:05:57.353371Z",
        "status": "succeeded"
    }
]

DELETE /refreshes/<refreshId>

実行中の更新操作をキャンセルするには、更新 ID に対して DELETE 動詞を使用します。

POST /sync

更新操作を実行したあと、その新しいデータをクエリのスケールアウトのためにレプリカと同期する必要がある場合があります。モデルの同期操作を実行するには、/sync 関数に対して POST 動詞を使用します。応答内の Location ヘッダーには、同期操作 ID が含まれています。

GET /sync 状態

同期操作の状態を確認するには、パラメーターとして操作 ID を渡す GET 動詞を使用します。応答の本文の例を次に示します。

{
    "operationId": "cd5e16c6-6d4e-4347-86a0-762bdf5b4875",
    "database": "AdventureWorks2",
    "UpdatedAt": "2017-12-09T02:44:26.18",
    "StartedAt": "2017-12-09T02:44:20.743",
    "syncstate": 2,
    "details": null
}

syncstate の値:

0: レプリケーション中。データベースファイルはターゲットフォルダーにレプリケートされています。
1: リハイドレート中。データベースは読み取り専用のサーバーインスタンスにリハイドレートされています。
2: 完了。同期操作は正常に完了しました。
3: 失敗。同期操作は失敗しました。
4: 終了処理中。同期操作は完了しましたが、クリーンアップ手順を実行中です。

コードサンプル

開始するための C# コードのサンプルは GitHub の RestApiSample にあります。

サンプルコードを使用するには

リポジトリを複製またはダウンロードします。 RestApiSample ソリューションを開きます。
行 client.BaseAddress = を検索して、ベース URL を指定します。

このコード例では、サービスプリンシパルの認証を使用しています。

サービスプリンシパル

詳細については、Azure portal でサービスプリンシパルを作成する方法に関するページと「サーバー管理者ロールへのサービスプリンシパルの追加」を参照して、Azure AS でサービスプリンシパルを設定し、必要なアクセス許可を割り当てる方法の手順に従ってください。次に、次の追加手順を実行してください。

コードサンプル内で "string authority = …" を見つけたら、"common" を自分の組織のテナント ID に置き換えます。
コメント化およびコメントの解除を行って、ClientCredential クラスで cred オブジェクトをインスタンス化します。 <アプリ ID> と <アプリキー> の値が安全な方法でアクセスされていることを確実にするか、サービスプリンシパルの証明書ベース認証を使用します。
サンプルを実行します。

こちらも参照ください

サンプル
 REST API

フィードバック

このページはお役に立ちましたか?

Last updated on 2025-06-06