sp_invoke_external_rest_endpoint (Transact-SQL)

[アーティクル]
12/06/2023

ストアドプロシージャは sp_invoke_external_rest_endpoint 、プロシージャへの入力引数として提供される HTTPS REST エンドポイントを呼び出します。

構文

EXEC @returnValue = sp_invoke_external_rest_endpoint
  [ @url = ] N'url'
  [ , [ @payload = ] N'request_payload' ]
  [ , [ @headers = ] N'http_headers_as_json_array' ]
  [ , [ @method = ] 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE' | 'HEAD' ]
  [ , [ @timeout = ] seconds ]
  [ , [ @credential = ] credential ]
  [ , @response OUTPUT ]

引数

[ @url = ] N'url'

呼び出される HTTPS REST エンドポイントの URL。 @urlは nvarchar(4000) で、既定値はありません。

[ @payload = ] N'request_payload'

HTTPS REST エンドポイントに送信するペイロードを含む JSON、XML、または TEXT 形式の Unicode 文字列。ペイロードは、有効な JSON ドキュメント、整形式の XML ドキュメント、またはテキストである必要があります。 @payloadは nvarchar(max) で、既定値はありません。

[ @headers = ] N'headers'

要求の一部として HTTPS REST エンドポイントに送信する必要があるヘッダー。ヘッダーは、フラット JSON (入れ子構造のない JSON ドキュメント) 形式を使用して指定する必要があります。許可されていないヘッダー名の一覧で定義されているヘッダーは、@headers パラメーターで明示的に渡された場合でも無視されます。HTTPS 要求の開始時に値が disカードまたはシステム指定の値に置き換えられます。

@headers パラメーターは nvarchar(4000) で、既定値はありません。

[ @method = ] N'method'

URL を呼び出すための HTTP メソッド。次のいずれかの値を指定する必要があります: GET, , POST, PUTPATCH, . HEADDELETE @methodは既定値として nvarchar(6)POST です。

[ @timeout = ] 秒

HTTPS 呼び出しを実行できる時間 (秒単位)。定義されたタイムアウト時間内に完全な HTTP 要求と応答を送信および受信できない場合は、ストアドプロシージャの実行が停止され、例外が発生します。タイムアウトは、HTTP 接続が開始されたときに開始され、応答とペイロード (含まれている場合) が受信されたときに終了します。 @timeoutは正の smallint で、既定値は 30 です。指定できる値: 1 ~ 230。

[ @credential = ] 資格情報

HTTPS 要求に認証情報を挿入するために使用する DATABA Standard Edition SCOPED CREDENTIAL オブジェクトを指定します。 @credentialは既定値のない sysname です。

@response 出力

呼び出されたエンドポイントから受信した応答を、指定された変数に渡すことを許可します。 @responseは nvarchar(max)です。

戻り値

HTTPS 呼び出しが完了し、受信した HTTP 状態コードが 2xx 状態コード (Success) の場合、実行は返0されます。受信した HTTP 状態コードが 2xx の範囲にない場合、戻り値は受信した HTTP 状態コードになります。 HTTPS 呼び出しをまったく実行できない場合は、例外がスローされます。

アクセス許可

EXECUTE ANY EXTERNAL ENDPOINT データベース権限が必要です。

次に例を示します。

GRANT EXECUTE ANY EXTERNAL ENDPOINT TO [<PRINCIPAL>];

応答形式

HTTP 呼び出しの応答と、呼び出されたエンドポイントによって返される結果のデータは、@response出力パラメーターを使用して使用できます。 @responseには、次のスキーマを持つ JSON ドキュメントが含まれている場合があります。

{
  "response": {
    "status": {
      "http": {
        "code": "",
        "description": ""
      }
    },
    "headers": {}
  },
  "result": {}
}

具体的には、次のように使用します。

response: HTTP 結果とその他の応答メタデータを含む JSON オブジェクト。
result: HTTP 呼び出しによって返される JSON ペイロード。受信した HTTP 結果が 204 (No Content) の場合は省略されます。

または、 @response には、次のスキーマを持つ XML ドキュメントが含まれている場合があります。

<output>
    <response>
        <status>
            <http code="" description=" " />
        </status>
        <headers>
            <header key="" value="" />
            <header key="" value="" />
        </headers>
    </response>
    <result>
    </result>
</output>

具体的には、次のように使用します。

response: HTTP 結果とその他の応答メタデータを含む XML オブジェクト。
result: HTTP 呼び出しによって返される XML ペイロード。受信した HTTP 結果が 204 (No Content) の場合は省略されます。

この response セクションでは、HTTP 状態コードと説明とは別に、受信した応答ヘッダーのセット全体がオブジェクトに headers 提供されます。次の例は、 response JSON のセクションを示しています (テキスト応答の構造も示しています)。

"response": {
  "status": {
    "http": {
      "code": 200,
      "description": "OK"
    }
  },
  "headers": {
    "Date": "Thu, 08 Sep 2022 21:51:22 GMT",
    "Content-Length": "1345",
    "Content-Type": "application\/json; charset=utf-8",
    "Server": "Kestrel",
    "Strict-Transport-Security": "max-age=31536000; includeSubDomains"
    }
  }

次の例は、XML のセクションを response 示しています。

<response>
    <status>
        <http code="200" description="OK" />
    </status>
    <headers>
        <header key="Date" value="Tue, 01 Apr 1976 21:12:04 GMT" />
        <header key="Content-Length" value="2112" />
        <header key="Content-Type" value="application/xml" />
        <header key="Server" value="Windows-Azure-Blob/1.0 Microsoft-HTTPAPI/2.0" />
        <header key="x-ms-request-id" value="31536000-64bi-64bi-64bi-31536000" />
        <header key="x-ms-version" value="2021-10-04" />
        <header key="x-ms-creation-time" value="Wed, 19 Apr 2023 22:17:33 GMT" />
        <header key="x-ms-server-encrypted" value="true" />
    </headers>
</response>

許可されるエンドポイント

次のサービスのエンドポイントへの呼び出しのみが許可されます。

Azure サービス	Domain
Azure Functions	*.azurewebsites.net
Azure アプリサービス	*.azurewebsites.net
Azure App Service Environment	*.appserviceenvironment.net
Azure Static Web Apps	*.azurestaticapps.net
Azure Logic Apps	*.logic.azure.com
Azure Event Hubs	*.servicebus.windows.net
Azure Event Grid	*.eventgrid.azure.net
Azure Cognitive Services	cognitiveservices.azure.com
Azure OpenAI	*.openai.azure.com
PowerApps/Dataverse	*.api.crm.dynamics.com
Microsoft Dynamics	*.dynamics.com
Azure Container Instances	*.azurecontainer.io
Azure Container Apps	*.azurecontainerapps.io
Power BI	api.powerbi.com
Microsoft Graph	graph.microsoft.com
Analysis Services	*.asazure.windows.net
IoT Central	*.azureiotcentral.com
API Management	*.azure-api.net
Azure Blob Storage	*.blob.core.windows.net
Azure Files	*.file.core.windows.net
Azure Queue Storage	*.queue.core.windows.net
Azure Table Storage	*.table.core.windows.net
Azure Communication Services	*.communications.azure.com
Bing Search	api.bing.microsoft.com
Azure Key Vault	*.vault.azure.net
Azure AI Search	*.search.windows.net

送信ファイアウォール規則制御メカニズムを使用して、外部エンドポイントへの送信アクセスをさらに制限できます。

Note

許可リスト内にない REST サービスを呼び出す場合は、API Management を使用して目的のサービスを安全に公開し、それを使用できるようにします sp_invoke_external_rest_endpoint。

制限

ペイロードのサイズ

ペイロードは、受信時と送信時の両方で、ネットワーク経由で送信されるときに UTF-8 エンコードされます。この形式では、サイズは 100 MB (メガバイト)に制限されます。

URL の長さ

最大 URL 長 (@url パラメーターを使用し、指定した資格情報がある場合はクエリ文字列に追加した後に生成されます) は 8 KB (キロバイト)。クエリ文字列の最大長 (クエリ文字列 + 資格情報クエリ文字列) は 4 KB (キロバイト)です。

ヘッダーのサイズ

要求ヘッダーと応答ヘッダーの最大サイズ (すべてのヘッダーフィールド: @headers パラメーター経由で渡されたヘッダー + 資格情報ヘッダー + システム提供のヘッダー) は 8 KB (キロバイト)です。

調整

外部 sp_invoke_external_rest_endpoint エンドポイントへの同時接続の数は、ワーカースレッドの 10% に制限され、最大 150 ワーカーに制限されます。単一データベースの調整はデータベースレベルで適用され、エラスティックプールではデータベースレベルとプールレベルの両方で調整が適用されます。

データベースが維持できるコンカレント接続の数をチェックするには、次のクエリを実行します。

SELECT
  [database_name],
  DATABASEPROPERTYEX(DB_NAME(), 'ServiceObjective') AS service_level_objective,
  [slo_name] as service_level_objective_long,
  [primary_group_max_outbound_connection_workers] AS max_database_outbound_connection,
  [primary_pool_max_outbound_connection_workers] AS max_pool_outbound_connection
FROM
  sys.dm_user_db_resource_governance
WHERE
  database_id = DB_ID();

最大同時接続数が既に達したときに、使用 sp_invoke_external_rest_endpoint する外部エンドポイントへの新しい接続が試行された場合は、エラー 10928 (エラスティックプールの制限に達した場合は 10936) が発生します。次に例を示します。

Msg 10928, Level 16, State 4, Procedure sys.sp_invoke_external_rest_endpoint_internal, Line 1 [Batch Start Line 0]
Resource ID : 1. The outbound connections limit for the database is 20 and has been reached.
See 'https://docs.microsoft.com/azure/azure-sql/database/resource-limits-logical-server' for assistance.

資格情報

一部の REST エンドポイントでは、適切に呼び出されるために認証が必要です。通常、認証は、クエリ文字列または要求で設定された HTTP ヘッダーに特定のキーと値のペアを渡すことによって行うことができます。

DATABA Standard Edition SCOPED CREDENTIALS を使用して、保護されたエンドポイントを呼び出すために使用sp_invoke_external_rest_endpointされる認証データ (ベアラートークンなど) を安全に格納できます。 DATABA Standard Edition SCOPED CREDENTIAL を作成するときは、IDENTITY パラメーターを使用して、呼び出されたエンドポイントに渡される認証データとその方法を指定します。 IDENTITY では、次の 3 つのオプションがサポートされています。

HTTPEndpointHeaders: 要求ヘッダーを使用して、指定された認証データを 送信します
HTTPEndpointQueryString: クエリ文字列を使用して指定された認証データを 送信します
Managed Identity: 要求ヘッダーを使用してシステム割り当て マネージド ID を 送信します

作成された DATABA Standard Edition SCOPED CREDENTIAL は、@credential パラメーターを使用して使用できます。

EXEC sp_invoke_external_rest_endpoint
  @url = N'https://<APP_NAME>.azurewebsites.net/api/<FUNCTION_NAME>?key1=value1',
  @credential = [https://<APP_NAME>.azurewebsites.net/api/<FUNCTION_NAME>]

この IDENTITY 値を使用すると、DATABA Standard Edition SCOPED CREDENTIAL が要求ヘッダーに追加されます。認証情報を含むキーと値のペアは、フラット JSON 形式を使用して Standard Edition CRET パラメーターを使用して指定する必要があります。次に例を示します。

CREATE DATABASE SCOPED CREDENTIAL [https://<APP_NAME>.azurewebsites.net/api/<FUNCTION_NAME>]
WITH IDENTITY = 'HTTPEndpointHeaders', SECRET = '{"x-functions-key":"<your-function-key-here>"}';

この IDENTITY 値を使用すると、DATABA Standard Edition SCOPED CREDENTIAL がクエリ文字列に追加されます。認証情報を含むキーと値のペアは、フラット JSON 形式を使用して Standard Edition CRET パラメーターを使用して指定する必要があります。次に例を示します。

CREATE DATABASE SCOPED CREDENTIAL [https://<APP_NAME>.azurewebsites.net/api/<FUNCTION_NAME>]
WITH IDENTITY = 'HTTPEndpointQueryString', SECRET = '{"code":"<your-function-key-here>"}';

‭‬パスワード‭は、Microsoft Entra 資格情報を使用した認証を提供します
MFA を使用したユニバーサルによる多要素認証の追加
統合では、Active Directory フェデレーションサービス (AD FS) (ADFS) などのフェデレーションプロバイダーを使用してシングルサインオン (SSO) エクスペリエンスを有効にする
サービスプリンシパルにより Azure アプリケーションからの認証が有効化されます
‭‬Managed Identity‭‬ は、Microsoft Entra ID が割り当てられたアプリケーションからの認証を有効にします

この IDENTITY 値を使用すると、DATABA Standard Edition SCOPED CREDENTIAL の認証情報は、データベースが存在する論理サーバーのシステム割り当てマネージド ID から取得され、要求ヘッダーで渡されます。 Standard Edition CRET は、呼び出されたエンドポイントの Microsoft Entra 認証を構成するために使用するAPP_ID (またはCLIENT_ID) に設定する必要があります。 (例: Microsoft Entra ログインを使用するように App Service または Azure Functions アプリを構成する)

CREATE DATABASE SCOPED CREDENTIAL [https://<APP_NAME>.azurewebsites.net/api/<FUNCTION_NAME>]
WITH IDENTITY = 'Managed Identity', SECRET = '{"resourceid":"<APP_ID>"}';

システム割り当てマネージド ID とユーザー割り当てマネージド ID の両方がサポートされています。

ユーザー割り当てマネージド ID が少なくとも 1 つ存在する場合、マネージド ID ベースのデータベーススコープ資格情報を使用する場合、定義されたプライマリ ID が認証に使用されます。
ユーザー割り当てマネージド ID が割り当てられていない場合、システム割り当てマネージド ID が有効になっている場合は、マネージド ID ベースのデータベーススコープ資格情報を使用する際の認証に使用されます。
ユーザー割り当てマネージド ID とシステム割り当てマネージド ID の両方が定義されている場合は、ユーザー割り当てマネージド ID が使用されます。
複数のユーザー割り当てマネージド ID が割り当てられている場合は、プライマリ ID のみが使用されます。

資格情報名の規則

作成された DATABA Standard Edition SCOPED CREDENTIAL を使用sp_invoke_external_rest_endpointするには、特定の規則に従う必要があります。規則は次のとおりです。

有効な URI である必要があります。
URL doメインは、許可リストに含まれるいずれかの操作メインにする必要があります
URL にクエリ文字列を含めてはなりません
呼び出された URL のプロトコル + 完全修飾 Doメイン名 (FQDN) は、資格情報名のプロトコル + FQDN と一致する必要があります
呼び出された URL パスの各部分は、資格情報名の URL パスのそれぞれの部分と完全に一致する必要があります
資格情報は、要求 URL よりも汎用的なパスを指す必要があります。たとえば、パス https://northwind.azurewebsite.net/customers 用に作成された資格情報を URL に使用することはできません https://northwind.azurewebsite.net

照合順序と資格情報名の規則

RFC 3986 セクション 6.2.2.1 では、「URI がジェネリック構文のコンポーネントを使用する場合、コンポーネント構文の等価性ルールが常に適用されます。つまり、スキームとホストで大文字と小文字が区別されない"、および RFC 7230 セクション 2.7.3 メンション"その他はすべて大文字と小文字が区別される方法で比較されます。

データベースレベルで設定された照合順序規則があるため、次のロジックが適用され、データベースの照合順序規則と上記の RFC メンション一貫性があります。 (たとえば、データベースが大文字と小文字を区別する照合順序を使用するように設定されている場合など、記述された規則は RFC 規則よりも制限が厳しい可能性があります)。

RFC を使用して URL と資格情報が一致するかどうかを確認します。これは次のことを意味します。
- 大文字と小文字を区別しない照合順序を使用してスキームとホストを確認する (Latin1_General_100_CI_AS_KS_WS_SC)
- 大文字と小文字を区別する照合順序で、URL の他のすべてのセグメントが比較されていることを確認します (Latin1_General_100_BIN2)
URL と資格情報がデータベースの照合順序規則を使用して一致することを確認します (URL エンコードは行いません)。

資格情報を使用するためのアクセス許可を付与する

DATABA Standard Edition SCOPED CREDENTIAL にアクセスするデータベースユーザーには、その資格情報を使用するためのアクセス許可が必要です。

資格情報を使用するには、データベースユーザーが特定の資格情報に対するアクセス許可を持っている REFERENCES 必要があります。

GRANT REFERENCES ON DATABASE SCOPED CREDENTIAL::[<CREDENTIAL_NAME>] TO [<PRINCIPAL>];

解説

待機の種類

呼び出されたサービスの呼び出しが完了するのを待機している場合 sp_invoke_external_rest_endpoint は、HTTP_EXTERNAL_CONNECTION待機の種類が報告されます。

HTTPS と TLS

少なくとも TLS 1.2 暗号化プロトコルで HTTPS を使用するように構成されているエンドポイントのみがサポートされます。

HTTP リダイレクト

sp_invoke_external_rest_endpoint は、呼び出されたエンドポイントからの応答として受信された HTTP リダイレクトに自動的には従いません。

HTTP ヘッダー

sp_invoke_external_rest_endpoint は、HTTP 要求に次のヘッダーを自動的に挿入します。

content-type: に設定 application/json; charset=utf-8
accept: 次に設定します。 application/json
user-agent: 次に例を設定 <EDITION>/<PRODUCT VERSION> します。 SQL Azure/12.0.2000.8

ユーザーエージェントは常にストアドプロシージャによって上書きされますが、コンテンツタイプと受け入れヘッダーの値は、@headers パラメーターを使用してユーザー定義できます。コンテンツタイプで指定できるのはメディアタイプディレクティブのみで、文字セットまたは境界ディレクティブを指定することはできません。

要求と応答のペイロードでサポートされているメディアの種類

ヘッダー のコンテンツタイプに使用できる値を次に示します。

application/json
application/vnd.microsoft.*.json
application/xml
application/vnd.microsoft.*.xml
application/vnd.microsoft.*+xml
application/x-www-form-urlencoded
テキスト/*

accept ヘッダーの場合、受け入れ可能な値は次のとおりです。

application/json
application/xml
テキスト/*

テキストヘッダーの種類の詳細については、IANA のテキスト型レジストリを参照してください。

Note

他のツール (cURL など) や、不眠症などの最新の REST クライアントを使用して REST エンドポイントの呼び出しをテストする場合は、同じ動作と結果を得るために自動的に挿入されるsp_invoke_external_rest_endpointのと同じヘッダーを含めるようにしてください。

ベストプラクティス

バッチ処理手法を使用する

Azure 関数やイベントハブなど、一連の行を REST エンドポイントに送信する必要がある場合は、送信される各行の HTTPS 呼び出しのオーバーヘッドを回避するために、行を 1 つの JSON ドキュメントにバッチ処理することをお勧めします。これは、次のようにステートメントを FOR JSON 使用して行うことができます。

-- create the payload
DECLARE @payload AS NVARCHAR(MAX);

SET @payload = (
        SELECT [object_id], [name], [column_id]
        FROM sys.columns
        FOR JSON AUTO
        );

-- invoke the REST endpoint
DECLARE @retcode INT,
    @response AS NVARCHAR(MAX);

EXEC @retcode = sp_invoke_external_rest_endpoint @url = '<REST_endpoint>',
    @payload = @payload,
    @response = @response OUTPUT;

-- return the result
SELECT @retcode, @response;

例

ここでは、Azure Functions や Azure Event Hubs などの一般的な Azure サービスと統合する方法の sp_invoke_external_rest_endpoint 例をいくつか紹介します。他のサービスと統合するためのその他のサンプルについては、GitHub を参照してください。

A. 認証なしで HTTP トリガーバインドを使用して Azure 関数を呼び出す

次の例では、匿名アクセスを許可する HTTP トリガーバインドを使用して Azure 関数を呼び出します。

DECLARE @ret INT, @response NVARCHAR(MAX);

EXEC @ret = sp_invoke_external_rest_endpoint
  @url = N'https://<APP_NAME>.azurewebsites.net/api/<FUNCTION_NAME>?key1=value1',
  @headers = N'{"header1":"value_a", "header2":"value2", "header1":"value_b"}',
  @payload = N'{"some":{"data":"here"}}',
  @response = @response OUTPUT;

SELECT @ret AS ReturnCode, @response AS Response;

B. 承認キーを使用して HTTP トリガーバインドを使用して Azure 関数を呼び出す

次の例では、承認キーを必要とするように構成された HTTP トリガーバインドを使用して Azure 関数を呼び出します。承認キーは、Azure Functions で必要に応じてヘッダーに x-function-key 渡されます。詳細については、「Azure Functions - API キーの承認」を参照してください。

CREATE DATABASE SCOPED CREDENTIAL [https://<APP_NAME>.azurewebsites.net/api/<FUNCTION_NAME>]
WITH IDENTITY = 'HTTPEndpointHeaders', SECRET = '{"x-functions-key":"<your-function-key-here>"}';

DECLARE @ret INT, @response NVARCHAR(MAX);

EXEC @ret = sp_invoke_external_rest_endpoint
  @url = N'https://<APP_NAME>.azurewebsites.net/api/<FUNCTION_NAME>?key1=value1',
  @headers = N'{"header1":"value_a", "header2":"value2", "header1":"value_b"}',
  @credential = [https://<APP_NAME>.azurewebsites.net/api/<FUNCTION_NAME>],
  @payload = N'{"some":{"data":"here"}}',
  @response = @response OUTPUT;

SELECT @ret AS ReturnCode, @response AS Response;

C: SAS トークンを使用して Azure Blob Storage からファイルの内容を読み取る

この例では、認証に SAS トークンを使用して Azure Blob Storage からファイルを読み取ります。結果は XML で返されるため、ヘッダー "Accept":"application/xml" を使用する必要があります。

DECLARE @ret INT, @response NVARCHAR(MAX);

EXEC @ret = sp_invoke_external_rest_endpoint
  @url = N'https://blobby.blob.core.windows.net/datafiles/my_favorite_blobs.txt?sp=r&st=2023-07-28T19:56:07Z&se=2023-07-29T03:56:07Z&spr=https&sv=2022-11-02&sr=b&sig=XXXXXX1234XXXXXX6789XXXXX',
  @headers = N'{"Accept":"application/xml"}',
  @method = 'GET',
  @response = @response OUTPUT;

SELECT @ret AS ReturnCode, @response AS Response;

D. Azure SQL Database マネージド ID を使用してイベントハブにメッセージを送信する

このサンプルでは、Azure SQL マネージド ID を使用して Event Hubs にメッセージを送信する方法を示します。データベースをホストする Azure SQL Database 論理サーバーのシステムマネージド ID が構成されていることを確認します。次に例を示します。

az sql server update -g <resource-group> -n <azure-sql-server> --identity-type SystemAssigned

その後、Azure SQL Server のマネージド ID が目的のイベントハブにメッセージ ("Azure Event Hubs Data Sender" ロール) を送信できるように Event Hubs を構成します。詳細については、「マネージド ID で Event Hubs を使用する」を参照してください。

これが完了したら、使用する Managed Identity データベーススコープの資格情報を定義するときに ID 名を使用 sp_invoke_external_rest_endpointできます。「Event Hubs リソースにアクセスするための Microsoft Entra ID を使用してアプリケーションを認証する」で説明されているように、Microsoft Entra 認証を使用するときに使用するリソース名 (または ID) は次のとおりですhttps://eventhubs.azure.net。

CREATE DATABASE SCOPED CREDENTIAL [https://<EVENT-HUBS-NAME>.servicebus.windows.net]
    WITH IDENTITY = 'Managed Identity',
        SECRET = '{"resourceid": "https://eventhubs.azure.net"}';
GO

DECLARE @Id UNIQUEIDENTIFIER = NEWID();
DECLARE @payload NVARCHAR(MAX) = (
        SELECT *
        FROM (
            VALUES (@Id, 'John', 'Doe')
            ) AS UserTable(UserId, FirstName, LastName)
        FOR JSON AUTO,
            WITHOUT_ARRAY_WRAPPER
        )
DECLARE @url NVARCHAR(4000) = 'https://<EVENT-HUBS-NAME>.servicebus.windows.net/from-sql/messages';
DECLARE @headers NVARCHAR(4000) = N'{"BrokerProperties": "' + STRING_ESCAPE('{"PartitionKey": "' + CAST(@Id AS NVARCHAR(36)) + '"}', 'json') + '"}'
DECLARE @ret INT, @response NVARCHAR(MAX);

EXEC @ret = sp_invoke_external_rest_endpoint @url = @url,
    @headers = @headers,
    @credential = [https://<EVENT-HUBS-NAME>.servicebus.windows.net],
    @payload = @payload,
    @response = @response OUTPUT;

SELECT @ret AS ReturnCode, @response AS Response;

E. Azure SQL Database スコープの資格情報を使用して Azure File Storage に対するファイルの読み取りと書き込みを行う

この例では、認証用に Azure SQL Database スコープの資格情報を使用して Azure File Storage にファイルを書き込み、その内容を返します。結果は XML で返されるため、ヘッダー "Accept":"application/xml" を使用する必要があります。

まず、Azure SQL Database のマスターキーを作成します

create master key encryption by password = '2112templesmlm2BTS21.qwqw!@0dvd'
go

次に、Azure Blob Storage アカウントによって提供される SAS トークンを使用して、データベーススコープの資格情報を作成します。

create database scoped credential [filestore]
with identity='SHARED ACCESS SIGNATURE',
secret='sv=2022-11-02&ss=bfqt&srt=sco&sp=seespotrun&se=2023-08-03T02:21:25Z&st=2023-08-02T18:21:25Z&spr=https&sig=WWwwWWwwWWYaKCheeseNXCCCCCCDDDDDSSSSSU%3D'
go

次に、ファイルを作成し、次の 2 つのステートメントでテキストを追加します。

declare @payload nvarchar(max) = (select * from (values('Hello from Azure SQL!', sysdatetime())) payload([message], [timestamp])for json auto, without_array_wrapper)
declare @response nvarchar(max), @url nvarchar(max), @headers nvarchar(1000);
declare @len int = len(@payload)

-- Create the File
set @url = 'https://myfiles.file.core.windows.net/myfiles/test-me-from-azure-sql.json'
set @headers = json_object(
        'x-ms-type': 'file',
        'x-ms-content-length': cast(@len as varchar(9)),
        'Accept': 'application/xml')
exec sp_invoke_external_rest_endpoint
    @url = @url,
    @method = 'PUT',
    @headers = @headers,
    @credential = [filestore],
    @response = @response output
select cast(@response as xml);

-- Add text to the File
set @headers = json_object(
        'x-ms-range': 'bytes=0-' + cast(@len-1 as varchar(9)),
        'x-ms-write': 'update',
        'Accept': 'application/xml');
set @url = 'https://myfiles.file.core.windows.net/myfiles/test-me-from-azure-sql.json'
set @url += '?comp=range'
exec sp_invoke_external_rest_endpoint
    @url = @url,
    @method = 'PUT',
    @headers = @headers,
    @payload = @payload,
    @credential = [filestore],
    @response = @response output
select cast(@response as xml)
go

最後に、次のステートメントを使用してファイルを読み取る

declare @response nvarchar(max);
declare @url nvarchar(max) = 'https://myfiles.file.core.windows.net/myfiles/test-me-from-azure-sql.json'
exec sp_invoke_external_rest_endpoint
    @url = @url,
    @headers = '{"Accept":"application/xml"}',
    @credential = [filestore],
    @method = 'GET',
    @response = @response output
select cast(@response as xml)
go

sp_invoke_external_rest_endpoint (Transact-SQL)

構文

引数

[ @url = ] N'url'

[ @payload = ] N'request_payload'

[ @headers = ] N'headers'

[ @method = ] N'method'

[ @timeout = ] 秒

[ @credential = ] 資格情報

@response 出力

戻り値

アクセス許可

応答形式

許可されるエンドポイント

制限

ペイロードのサイズ

URL の長さ

ヘッダーのサイズ

調整

資格情報

資格情報名の規則

照合順序と資格情報名の規則

資格情報を使用するためのアクセス許可を付与する

解説

待機の種類

HTTPS と TLS

HTTP リダイレクト

HTTP ヘッダー

要求と応答のペイロードでサポートされているメディアの種類

ベストプラクティス

バッチ処理手法を使用する

例

A. 認証なしで HTTP トリガーバインドを使用して Azure 関数を呼び出す

B. 承認キーを使用して HTTP トリガーバインドを使用して Azure 関数を呼び出す

C: SAS トークンを使用して Azure Blob Storage からファイルの内容を読み取る

D. Azure SQL Database マネージド ID を使用してイベントハブにメッセージを送信する

E. Azure SQL Database スコープの資格情報を使用して Azure File Storage に対するファイルの読み取りと書き込みを行う

フィードバック

フィードバック

その他のリソース

sp_invoke_external_rest_endpoint (Transact-SQL)

構文

引数

[ @url = ] N'url'

[ @payload = ] N'request_payload'

[ @headers = ] N'headers'

[ @method = ] N'method'

[ @timeout = ] 秒

[ @credential = ] 資格情報

@response 出力

戻り値

アクセス許可

応答形式

許可されるエンドポイント

制限

ペイロードのサイズ

URL の長さ

ヘッダーのサイズ

調整

資格情報

資格情報名の規則

照合順序と資格情報名の規則

資格情報を使用するためのアクセス許可を付与する

解説

待機の種類

HTTPS と TLS

HTTP リダイレクト

HTTP ヘッダー

要求と応答のペイロードでサポートされているメディアの 種類

ベスト プラクティス

バッチ処理手法を使用する

例

A. 認証なしで HTTP トリガー バインドを使用して Azure 関数を呼び出す

B. 承認キーを使用して HTTP トリガー バインドを使用して Azure 関数を呼び出す

C: SAS トークンを使用して Azure Blob Storage からファイルの内容を読み取る

D. Azure SQL Database マネージド ID を使用してイベント ハブにメッセージを送信する

E. Azure SQL Database スコープの資格情報を使用して Azure File Storage に対するファイルの読み取りと書き込みを行う

関連するコンテンツ

フィードバック

フィードバック

その他のリソース

要求と応答のペイロードでサポートされているメディアの種類

ベストプラクティス

A. 認証なしで HTTP トリガーバインドを使用して Azure 関数を呼び出す

B. 承認キーを使用して HTTP トリガーバインドを使用して Azure 関数を呼び出す

D. Azure SQL Database マネージド ID を使用してイベントハブにメッセージを送信する