sp_invoke_external_rest_endpoint (Transact-SQL)

適用対象: Azure SQL Database

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

構文

Transact-SQL 構文表記規則

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 ドキュメント) 形式を使用して指定する必要があります。 Forbidden ヘッダー名リストで定義されているヘッダーは、@headers パラメーターで明示的に渡された場合でも無視されます。HTTPS 要求を開始するときに、その値は破棄されるか、システム指定の値に置き換えられます。

@headers パラメーターは、既定値のない nvarchar(4000)です。

[ @method = ] N'method'

URL を呼び出すための HTTP メソッド。 GET、POST、PUT、PATCH、DELETE、HEADのいずれかの値を指定する必要があります。 @methodは既定値としてPOSTnvarchar(6)です。

[ @timeout = ] 秒

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

[ @credential = ] credential

HTTPS 要求に認証情報を挿入するために使用される DATABASE 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 オブジェクトに提供されます。 次の例は、JSON の response セクションを示しています (テキスト応答の構造も示しています)。

"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>

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

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

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

制限

ペイロードのサイズ

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

URL の長さ

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

ヘッダーのサイズ

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

調整

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

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

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 ヘッダーに特定のキーと値のペアを渡すことによって行うことができます。

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

• HTTPEndpointHeaders: Request ヘッダーを使用して、指定された認証データを送信します
• HTTPEndpointQueryString: Query 文字列を使用して指定された認証データを送信します
• Managed Identity: 要求ヘッダーを使用して、システム割り当て 管理 ID を送信します

作成された DATABASE 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>]

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

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

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

資格情報名の規則

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

• 有効な URI である必要があります。
• URL ドメインは、許可リストに含まれているドメインのいずれかである必要があります
• URL にクエリ文字列を含めてはなりません
• 呼び出された URL のプロトコル + 完全修飾ドメイン名 (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 規則よりも制限が厳しい可能性があります)。

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

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

DATABASE 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

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

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

ヘッダー content-type に使用できる値を次に示します。

• 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 の テキスト型レジストリを参照してください。

ベスト プラクティス

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

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;

例

ここでは、 sp_invoke_external_rest_endpoint を使用して、Azure Functions や Azure Event Hubs などの一般的な Azure サービスと統合する方法の例をいくつか紹介します。 他のサービスと統合するためのその他のサンプルについては、 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 論理サーバーの System Managed Identity が構成されていることを確認します。次に例を示します。

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 を使用する」を参照してください。

これが完了したら、sp_invoke_external_rest_endpointによって使用されるデータベース スコープの資格情報を定義するときに、Managed Identity ID 名を使用できます。 で説明されているように、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

関連するコンテンツ

• Azure SQL Database でのリソース管理
• sys.dm_resource_governor_resource_pools_history_ex
• sys.dm_resource_governor_workload_groups_history_ex
• sys.dm_user_db_resource_governance
• GRANT (データベース アクセス許可の許可)
• CREATE DATABASE SCOPED CREDENTIAL (Transact-SQL)
• API Management
• sp_invoke_external_rest_endpointの使用サンプル