MATLAB を使用してデータのクエリを実行する

[アーティクル]
11/24/2023

MATLAB は、データの分析、アルゴリズムの開発、モデルの作成に使用されるプログラミングおよび数値コンピューティングプラットフォームです。この記事では、MATLAB for Azure Data Explorerで承認トークンを取得する方法と、トークンを使用してクラスターと対話する方法について説明します。

前提条件

MATLAB の実行に使用するオペレーティングシステムのタブを選択します。

Windows OS
Linux

NuGet から Microsoft Identity Client パッケージと Microsoft Identity Abstractions パッケージをダウンロードします。
ダウンロードしたパッケージと DLL ファイルを lib\net45 から任意のフォルダーに抽出します。この記事では、 フォルダー C:\Matlab\DLL を使用します。

JDK 8 と Maven をインストールします。
Azure Services リポジトリの MATLAB インターフェイスを複製します。
```
git clone https://github.com/mathworks-ref-arch/matlab-azure-services.git
```
MATLAB Azure SDK jar をビルドします。
```
cd matlab-azure-services/Software/Java
mvn clean package
```
ビルドでは、ファイルを生成する必要があります。 Software/MATLAB/lib/jar/azure-common-sdk-0.2.0.jar
MATLAB スタジオで jar ファイルを読み込み、java 静的クラスパスに追加します。
```
edit(fullfile(prefdir,'javaclasspath.txt'));
```
java 静的クラスパスファイルで、jar ファイルに対応するエントリを追加します。
```
(full-path)/matlab-azure-services/Software/MATLAB/lib/jar/azure-common-sdk-0.2.0.jar
```

MATLAB IDE を再起動します。再読み込みが完了したら、matlab-azure-services\Software\MATLAB\startup.m で使用可能な startup.m スクリプトを実行します。これにより、Azure サービスにアクセスするためにすべての前提条件関数が設定されます。出力は次のようになります。

>> startup
Adding Azure Paths
------------------
Adding: matlab-azure-services/Software/MATLAB/app
Adding: matlab-azure-services/Software/MATLAB/app/functions
Adding: matlab-azure-services/Software/MATLAB/app/system
Adding: matlab-azure-services/Software/MATLAB/lib
Adding: matlab-azure-services/Software/MATLAB/config
Skipping: matlab-azure-services/Software/Utilities
Checking the static Java classpath for: matlab-azure-services/Software/MATLAB/lib/jar/azure-common-sdk-0.2.0.jar
Found: azure-common-sdk-0.2.0.jar

ユーザー認証を実行する

ユーザー認証を使用すると、ユーザーはブラウザーウィンドウからサインインするように求められます。サインインが成功すると、ユーザー承認トークンが付与されます。このセクションでは、この対話型サインインフローを構成する方法について説明します。

ユーザー認証を実行するには:

Windows OS
Linux

承認に必要な定数を定義します。これらの値の詳細については、「認証パラメーター」を参照してください。

% The Azure Data Explorer cluster URL
clusterUrl = 'https://<adx-cluster>.kusto.windows.net';
% The Azure AD tenant ID
tenantId = '';
% Send a request to https://<adx-cluster>.kusto.windows.net/v1/rest/auth/metadata
% The appId should be the value of KustoClientAppId
appId = '';
% The Azure AD scopes
scopesToUse = strcat(clusterUrl,'/.default ');

MATLAB Studio で、抽出された DLL ファイルを読み込みます。

% Access the folder that contains the DLL files
dllFolder = fullfile("C:","Matlab","DLL");

% Load the referenced assemblies in the MATLAB session
matlabDllFiles = dir(fullfile(dllFolder,'*.dll'));
for k = 1:length(matlabDllFiles)
    baseFileName = matlabDllFiles(k).name;
    fullFileName = fullfile(dllFolder,baseFileName);
    fprintf(1, 'Reading  %s\n', fullFileName);
end
    % Load the downloaded assembly in MATLAB
    NET.addAssembly(fullFileName);

PublicClientApplicationBuilder を使用して、ユーザーの対話型サインインを求めます。

% Create an PublicClientApplicationBuilder
app = Microsoft.Identity.Client.PublicClientApplicationBuilder.Create(appId)...
    .WithAuthority(Microsoft.Identity.Client.AzureCloudInstance.AzurePublic,tenantId)...
    .WithRedirectUri('http://localhost:8675')...
    .Build();

% System.Net.ServicePointManager.SecurityProtocol = System.Net.SecurityProtocolType.Tls12;
NET.setStaticProperty ('System.Net.ServicePointManager.SecurityProtocol',System.Net.SecurityProtocolType.Tls12)
% Start with creating a list of scopes
scopes = NET.createGeneric('System.Collections.Generic.List',{'System.String'});
% Add the actual scopes
scopes.Add(scopesToUse);
fprintf(1, 'Using appScope  %s\n', scopesToUse);

% Get the token from the service
% and show the interactive dialog in which the user can login
tokenAcquirer = app.AcquireTokenInteractive(scopes);
result = tokenAcquirer.ExecuteAsync;

% Extract the token and when it expires
% and retrieve the returned token
token = char(result.Result.AccessToken);
fprintf(2, 'User token aquired and will expire at %s & extended expires at %s', result.Result.ExpiresOn.LocalDateTime.ToString,result.Result.ExtendedExpiresOn.ToLocalTime.ToString);

承認トークンを使用して、 REST API を使用してクラスターに対してクエリを実行します。

options=weboptions('HeaderFields',{'RequestMethod','POST';'Accept' 'application/json';'Authorization' ['Bearer ', token]; 'Content-Type' 'application/json; charset=utf-8'; 'Connection' 'Keep-Alive'; 'x-ms-app' 'Matlab'; 'x-ms-client-request-id' 'Matlab-Query-Request'});

% The DB and KQL variables represent the database and query to execute
querydata = struct('db', "<DB>", 'csl', "<KQL>");
querryresults  = webwrite("https://sdktestcluster.westeurope.dev.kusto.windows.net/v2/rest/query", querydata, options);

% Extract the results row
results=querryresults{3}.Rows

関連する資格情報を使用して、作業ディレクトリに Auth.json ファイルを作成します。から https://<adx-cluster>.kusto.windows.net/v1/rest/auth/metadata 返される KustoClientAppId は、以下の ClientId の値に置き換える必要があります。
```
{
    "AuthMethod": "InteractiveBrowser",
    "TenantId" : "<AAD Tenant / Authority ID for the login>",
    "ClientId" : "<Client ID>",
    "RedirectUrl": "http://localhost:8675"
}
```

次のようにクラスターにクエリを実行します。

% References the credential file created in the previous step
credentials = configureCredentials('Auth.json');

% Point the scopes to the Azure Data Explorer cluster that we want to query
request = azure.core.credential.TokenRequestContext();
request.addScopes('<https://adx-cluster-changeme.kusto.windows.net/.default>');
token=credentials.getToken(request);

% Prepare to query the cluster
options=weboptions('HeaderFields',{'RequestMethod','POST';'Accept' 'application/json';'Authorization' ['Bearer ', token.getToken()]; 'Content-Type' 'application/json; charset=utf-8'; 'Connection' 'Keep-Alive'; 'x-ms-app' 'Matlab'; 'x-ms-client-request-id' 'Matlab-Query-Request'});

% The DB and KQL variables represent the database and query to execute
querydata = struct('db', "<DB>", 'csl', "<KQL>");
querryresults  = webwrite('<https://adx-cluster-changeme.kusto.windows.net/v2/rest/query>', querydata, options);

% The results row can be extracted as follows
results=querryresults{3}.Rows

アプリケーション認証を実行する

Microsoft Entraアプリケーションの承認は、対話型サインインが必要ではなく、自動実行が必要なシナリオに使用できます。

アプリケーション認証を実行するには:

Windows OS
Linux

Microsoft Entra アプリケーションをプロビジョニングします。 [ リダイレクト URI] で、[ Web ] を選択し、URI として入力 http://localhost:8675 します。

承認に必要な定数を定義します。これらの値の詳細については、「認証パラメーター」を参照してください。

% The Azure Data Explorer cluster URL
clusterUrl = 'https://<adx-cluster>.kusto.windows.net';
% The Azure AD tenant ID
tenantId = '';
% The Azure AD application ID and key
appId = '';
appSecret = '';

MATLAB Studio で、抽出された DLL ファイルを読み込みます。

 % Access the folder that contains the DLL files
 dllFolder = fullfile("C:","Matlab","DLL");

 % Load the referenced assemblies in the MATLAB session
 matlabDllFiles = dir(fullfile(dllFolder,'*.dll'));
 for k = 1:length(matlabDllFiles)
     baseFileName = matlabDllFiles(k).name;
     fullFileName = fullfile(dllFolder,baseFileName);
     fprintf(1, 'Reading  %s\n', fullFileName);
 end
     % Load the downloaded assembly
     NET.addAssembly(fullFileName);

ConfidentialClientApplicationBuilder を使用して、Microsoft Entra アプリケーションで非対話型の自動サインインを実行します。

%  Create an ConfidentialClientApplicationBuilder
app = Microsoft.Identity.Client.ConfidentialClientApplicationBuilder.Create(appId)...
    .WithAuthority(Microsoft.Identity.Client.AzureCloudInstance.AzurePublic,tenantId)...
    .WithRedirectUri('http://localhost:8675')...
    .WithClientSecret(appSecret)...
    .Build();

% System.Net.ServicePointManager.SecurityProtocol = System.Net.SecurityProtocolType.Tls12;
NET.setStaticProperty ('System.Net.ServicePointManager.SecurityProtocol',System.Net.SecurityProtocolType.Tls12)
% Start with creating a list of scopes
scopes = NET.createGeneric('System.Collections.Generic.List',{'System.String'});
% Add the actual scopes
scopes.Add(scopesToUse);
fprintf(1, 'Using appScope  %s\n', scopesToUse);

% Get the token from the service and cache it until it expires
tokenAcquirer = app.AcquireTokenForClient(scopes);
result = tokenAcquirer.ExecuteAsync;

% Extract the token and when it expires
% retrieve the returned token
token = char(result.Result.AccessToken);
fprintf(2, 'User token aquired and will expire at %s & extended expires at %s', result.Result.ExpiresOn.LocalDateTime.ToString,result.Result.ExtendedExpiresOn.ToLocalTime.ToString);

承認トークンを使用して、 REST API を使用してクラスターに対してクエリを実行します。

options=weboptions('HeaderFields',{'RequestMethod','POST';'Accept' 'application/json';'Authorization' ['Bearer ', token]; 'Content-Type' 'application/json; charset=utf-8'; 'Connection' 'Keep-Alive'; 'x-ms-app' 'Matlab'; 'x-ms-client-request-id' 'Matlab-Query-Request'});

% The DB and KQL variables represent the database and query to execute
querydata = struct('db', "<DB>", 'csl', "<KQL>");
querryresults  = webwrite("https://sdktestcluster.westeurope.dev.kusto.windows.net/v2/rest/query", querydata, options);

% Extract the results row
results=querryresults{3}.Rows

関連する資格情報を使用して、作業ディレクトリに Auth.json ファイルを作成します。

{
    "AuthMethod": "ClientSecret",
    "TenantId" : "<AAD Tenant / Authority ID for the login>",
    "ClientId" : "<Client ID of the Azure AD application>",
    "ClientSecret": "<Client Key of the Azure AD application>",
    "RedirectUrl": "http://localhost:8675"
}

次のようにクラスターにクエリを実行します。

% References the credential file created in the previous step
credentials = configureCredentials('Auth.json');

% Point the scopes to the Azure Data Explorer cluster that we want to query
request = azure.core.credential.TokenRequestContext();request.addScopes('<https://adx-cluster-changeme.kusto.windows.net/.default>');
token=credentials.getToken(request);

% Prepare to query the cluster
options=weboptions('HeaderFields',{'RequestMethod','POST';'Accept' 'application/json';'Authorization' ['Bearer ', token.getToken()]; 'Content-Type' 'application/json; charset=utf-8'; 'Connection' 'Keep-Alive'; 'x-ms-app' 'Matlab'; 'x-ms-client-request-id' 'Matlab-Query-Request'});

% The DB and KQL variables represent the database and query to execute
querydata = struct('db', "<DB>", 'csl', "<KQL>");
querryresults  = webwrite('<https://adx-cluster-changeme.kusto.windows.net/v2/rest/query>', querydata, options);

% The results row can be extracted as follows
results=querryresults{3}.Rows

REST API を使用してクラスターにクエリを実行する

次の方法で共有

MATLAB を使用してデータのクエリを実行する

前提条件

ユーザー認証を実行する

アプリケーション認証を実行する

フィードバック

その他のリソース

次の方法で共有

MATLAB を使用してデータのクエリを実行する

前提条件

ユーザー認証を実行する

アプリケーション認証を実行する

関連コンテンツ

フィードバック

その他のリソース