sp_invoke_external_rest_endpoint (Transact-SQL)

Применимо к: База данных SQL Azure

Хранимая sp_invoke_external_rest_endpoint процедура вызывает конечную точку REST HTTPS, предоставленную в качестве входного аргумента для процедуры.

Синтаксис

Соглашения о синтаксисе 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'

URL-адрес вызываемой конечной точки REST HTTPS. @url — nvarchar(4000) без значения по умолчанию.

[ @payload = ] N'request_payload'

Строка Юникода в формате JSON, XML или TEXT, содержащая полезные данные для отправки в конечную точку REST HTTPS. Полезные данные должны быть допустимым документом JSON, хорошо сформированным XML-документом или текстом. @payload — nvarchar(max) без значения по умолчанию.

[ @headers = ] N'headers'

Заголовки, которые должны быть отправлены в рамках запроса в конечную точку REST HTTPS. Заголовки должны быть указаны с помощью неструктурированного формата JSON (документа JSON без вложенных структур). Заголовки, определенные в списке имен запрещенных заголовков, будут игнорироваться даже при явном передаче в параметре @headers ; их значения будут удалены или заменены системными значениями при запуске HTTPS-запроса.

Параметр @headers — nvarchar(4000) без значения по умолчанию.

[ @method = ] N'method'

Метод HTTP для вызова URL-адреса. Должно быть одним из следующих значений: GET, POST, PUT, PATCH, DELETE. HEAD @method — nvarchar(6) с POST значением по умолчанию.

[ @timeout = ] секунды

Время в секундах, разрешено для выполнения вызова HTTPS. Если полный HTTP-запрос и ответ не могут быть отправлены и получены в течение определенного времени ожидания в секундах, выполнение хранимой процедуры прекращается, и возникает исключение. Время ожидания начинается, когда http-подключение начинается и заканчивается, когда ответ, и полезные данные, включенные, если таковые имеются, были получены. @timeout является положительным небольшим значением по умолчанию 30. Принятые значения: от 1 до 230.

[ @credential = ] учетные данные

Укажите, какой объект DATABASE SCOPED CREDENTIAL используется для внедрения сведений о проверке подлинности в HTTPS-запросе. @credential — sysname без значения по умолчанию.

@response ВЫПУСК

Разрешите ответ, полученный от вызываемой конечной точки, передаваться в указанную переменную. @response — nvarchar(max).

Возвращаемые значения

Выполнение возвращается 0 , если был выполнен вызов HTTPS, а полученный код состояния HTTP — это код состояния 2xx (Success). Если код состояния 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": {}
}

В частности:

• ответ: объект JSON, содержащий результат HTTP и другие метаданные ответа.
• результат: полезные данные JSON, возвращаемые вызовом HTTP. Опущен, если полученный результат 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>

В частности:

• ответ: XML-объект, содержащий результат HTTP и другие метаданные ответа.
• результат: полезные данные XML, возвращаемые вызовом HTTP. Опущен, если полученный результат 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"
    }
  }

В следующем примере показан response раздел в ФОРМАТЕ XML:

<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 МБ.

Длина URL-адреса

Максимальная длина URL-адреса (созданная после использования параметра @url и добавление указанных учетных данных в строку запроса( при наличии) составляет 8 КБ; максимальная длина строки запроса (строка запроса и строка запроса учетных данных) составляет 4 КБ.

Размер заголовков

Максимальный размер заголовка запроса и ответа (все поля заголовков: заголовки, передаваемые через параметр @headers + заголовки учетных данных + предоставленные системой заголовки) составляет 8 КБ.

Регулирование

Количество одновременных подключений к внешним конечным точкам, выполненных через 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, заданных запросом.

Можно использовать DATABASE SCOPED CREDENTIALS для безопасного хранения данных проверки подлинности (например, маркера носителя) sp_invoke_external_rest_endpoint для вызова защищенной конечной точки. При создании DATABASE SCOPED CREDENTIAL используйте параметр IDENTITY, чтобы указать, какие данные проверки подлинности будут передаваться в вызываемую конечную точку и как. IDENTITY поддерживает три варианта:

• HTTPEndpointHeaders: отправка указанных данных проверки подлинности с помощью заголовков запроса
• HTTPEndpointQueryString: отправка указанных данных проверки подлинности с помощью строки запроса
• Managed Identity: отправка управляемого удостоверения, назначаемого системой, с помощью заголовков запроса
• Shared Access Signatures (SAS): предоставление ограниченного делегированного доступа к ресурсам с помощью подписанного URL-адреса

Созданный ПАРАМЕТР 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 должны соответствовать определенным правилам, чтобы использовать их sp_invoke_external_rest_endpoint. Ниже приведены правила.

• Должен быть допустимым URL-адресом
• Домен URL-адреса должен быть одним из этих доменов, включенных в список разрешений.
• URL-адрес не должен содержать строку запроса
• Протокол + полное доменное имя (FQDN) вызываемого URL-адреса должно соответствовать протоколу +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. Проверьте, совпадают ли URL-адреса и учетные данные с помощью RFC, то есть:
   • Проверьте схему и узел с помощью нечувствительной сортировки регистра (Latin1_General_100_CI_AS_KS_WS_SC)
   • Проверьте все остальные сегменты URL-адреса сравниваются в параметров сортировки с учетом регистра (Latin1_General_100_BIN2)
2. Убедитесь, что URL-адрес и учетные данные соответствуют правилам сортировки базы данных (и без кодирования URL-адресов).

Предоставление разрешений на использование учетных данных

Пользователи базы данных, обращающиеся к учетным данным DATABASE SCOPED, должны иметь разрешение на использование учетных данных.

Чтобы использовать учетные данные, пользователь базы данных должен иметь REFERENCES разрешение на определенные учетные данные:

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

Замечания

Тип ожидания

Когда sp_invoke_external_rest_endpoint ожидает завершения вызова вызываемой службы, он сообщит о типе ожидания HTTP_EXTERNAL_CONNECTION.

HTTPS и TLS

Поддерживаются только конечные точки, настроенные для использования HTTPS с протоколом шифрования TLS 1.2.

Перенаправления HTTP

sp_invoke_external_rest_endpoint не будет автоматически следовать перенаправлению HTTP, полученному в качестве ответа от вызываемой конечной точки.

Заголовки HTTP

sp_invoke_external_rest_endpoint автоматически внедряет следующие заголовки в HTTP-запрос:

• тип контента: задано значение application/json; charset=utf-8
• accept: set to application/json
• user-agent: задайте <EDITION>/<PRODUCT VERSION> для примера: SQL Azure/12.0.2000.8

Хотя агент пользователя всегда будет перезаписан хранимой процедурой, тип контента и принимать значения заголовков можно использовать с помощью параметра @headers . Только директива типа носителя может быть указана в типе контента и указана директива charset или граничная директива.

Полезные данные запроса и ответа, поддерживаемые типы носителей

Ниже приведены допустимые значения для типа контента заголовка.

• 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.

Рекомендации

Использование метода пакетной обработки

Если необходимо отправить набор строк в конечную точку REST, например в функцию Azure или концентратор событий, рекомендуется пакетировать строки в один документ JSON, чтобы избежать затрат на вызов HTTPS для каждой строки, отправляемой строки. Это можно сделать с помощью инструкции 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, такими как sp_invoke_external_rest_endpoint Функции Azure или Центры событий Azure. Дополнительные примеры для интеграции с другими службами можно найти на сайте GitHub.

А. Вызов функции Azure с помощью привязки триггера HTTP без проверки подлинности

В следующем примере вызывается функция Azure с помощью привязки триггера HTTP, разрешающей анонимный доступ.

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. Вызов функции Azure с помощью привязки триггера HTTP с ключом авторизации

В следующем примере вызывается функция Azure с помощью привязки триггера HTTP, настроенной для требования ключа авторизации. Ключ авторизации будет передан в заголовке x-function-key в соответствии с требованиями Функции Azure. Дополнительные сведения см. в разделе Функции Azure — авторизация ключа 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. Чтение содержимого файла из Хранилище BLOB-объектов Azure с помощью маркера SAS

В этом примере файл считывается из Хранилище BLOB-объектов Azure с помощью маркера SAS для проверки подлинности. Результаты будут возвращены в ФОРМАТЕ 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. Отправка сообщения в концентратор событий с помощью управляемого удостоверения База данных SQL Azure

В этом примере показано, как отправлять сообщения в Центры событий с помощью управляемого удостоверения SQL Azure. Убедитесь, что вы настроили управляемое удостоверение системы для База данных SQL Azure логического сервера, на котором размещена база данных, например:

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

После этого настройте Центры событий, чтобы позволить Управляемому удостоверению SQL Server Azure отправлять сообщения (роль "Центры событий Azure отправителю данных") в нужный концентратор событий. Дополнительные сведения см. в разделе "Использование центров событий с управляемыми удостоверениями".

После этого можно использовать Managed Identity имя удостоверения при определении учетных данных в области базы данных, которые будут использоваться sp_invoke_external_rest_endpoint. Как описано в статье Аутентификация приложения с помощью идентификатора Microsoft Entra для доступа к ресурсам Центров событий, имя ресурса (или идентификатор), используемое при использовании проверки подлинности Microsoft Entra: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;

Е. Чтение и запись файла в хранилище файлов Azure с помощью учетных данных База данных SQL Azure области

В этом примере файл записывается в хранилище файлов Azure с помощью База данных SQL Azure учетных данных для проверки подлинности, а затем возвращает содержимое. Результаты будут возвращены в ФОРМАТЕ XML, поэтому потребуется использовать заголовок "Accept":"application/xml" .

Начните с создания главного ключа для База данных SQL Azure

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

Затем создайте учетные данные в области базы данных с помощью маркера SAS, предоставленного учетной записью Хранилище BLOB-объектов Azure.

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

Затем создайте файл и добавьте в него текст со следующими двумя операторами:

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

Связанный контент

• Управление ресурсами в базе данных SQL Azure
• 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
• примеры использования sp_invoke_external_rest_endpoint