sp_invoke_external_rest_endpoint (Transact-SQL)

Aplica-se a: SQL Server 2025 (17.x) Versão prévia do Banco de Dados SQL do Azurebanco de dadosSQL do Banco de Dados SQL do Azure banco de dados SQL gerenciadono Microsoft Fabric

O sp_invoke_external_rest_endpoint procedimento armazenado invoca um ponto de extremidade REST HTTPS fornecido como um argumento de entrada para o procedimento.

Observação

O sp_invoke_external_rest_endpoint procedimento armazenado está em versão prévia para a versão prévia do SQL Server 2025 (17.x).

Maneiras de reduzir o risco de acesso não autorizado ou transferência de dados

Cuidado

Usar o procedimento armazenado sp_invoke_external_rest_endpoint permite a transferência de dados para uma entidade externa.

Para atenuar o risco de acesso não autorizado ou transferência de dados, considere as seguintes práticas recomendadas de segurança:

• Implementar controles de acesso fortes: verifique se somente usuários autorizados têm acesso a dados confidenciais e pontos de extremidade da API REST. Use o princípio de privilégios mínimos, bem como funções de banco de dados e privilégios.
• autenticação e autorização adequadas: verifique se todas as chamadas REST são autenticadas e autorizadas a impedir o acesso não autorizado.
• Monitorar e auditar o acesso: monitore e audite regularmente o acesso ao banco de dados e às chamadas à API REST para detectar atividades suspeitas.
• avaliações regulares de segurança: realize avaliações regulares de segurança e verificações de vulnerabilidade para identificar e reduzir possíveis riscos.
• Treinamento de funcionários: instruir os funcionários sobre os riscos de exfiltração de dados e a importância de seguir protocolos de segurança.

Sintaxe

Convenções de sintaxe de Transact-SQL

EXECUTE @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 ]

Argumentos

@url [ = ] N'url'

URL do ponto de extremidade REST HTTPS a ser chamado. @url é nvarchar(4000) sem padrão.

@payload [ = ] N'request_payload'

Cadeia de caracteres Unicode em um formato JSON, XML ou TEXT que contém a carga a ser enviada para o ponto de extremidade REST HTTPS. As cargas devem ser um documento JSON válido, um documento XML bem formado ou texto. @payload é nvarchar(max) sem padrão.

@headers [ = ] N'cabeçalhos'

Cabeçalhos que devem ser enviados como parte da solicitação para o ponto de extremidade REST HTTPS. Os cabeçalhos devem ser especificados usando um formato JSON simples (um documento JSON sem estruturas aninhadas). Cabeçalhos definidos na lista de nomes de cabeçalhos proibidos são ignorados mesmo se explicitamente passados no parâmetro @headers ; seus valores são descartados ou substituídos por valores fornecidos pelo sistema ao iniciar a solicitação HTTPS.

O parâmetro @headers é nvarchar(4000) sem padrão.

@method [ = ] N'método'

HTTP para chamar a URL. Deve ser um dos seguintes valores: GET, POST, PUT, PATCH, DELETE, , HEAD. @method é nvarchar(6) com POST o valor padrão.

@timeout [ = ] segundos

Tempo em segundos permitido para que a chamada HTTPS seja executada. Se a solicitação e a resposta HTTP completas não puderem ser enviadas e recebidas dentro do tempo limite definido em segundos, a execução do procedimento armazenado será interrompida e uma exceção será gerada. O tempo limite começa quando a conexão HTTP é iniciada e termina quando a resposta e a carga incluída, se houver, são recebidas. @timeout é um smallint positivo com um valor padrão 30. Valores aceitos: 1 a 230.

@credential [ = ] credencial

Indique qual objeto DATABASE SCOPED CREDENTIAL é usado para injetar informações de autenticação na solicitação HTTPS. @credential é sysname sem valor padrão.

@response SAÍDA

Permita que a resposta recebida do ponto de extremidade chamado seja passada para a variável especificada. @response é nvarchar(max).

Valor retornado

A execução retornará 0 se a chamada HTTPS tiver sido feita e o código de status HTTP recebido for um código de status 2xx (Success). Se o código de status HTTP recebido não estiver no intervalo 2xx, o valor retornado será o código de status HTTP recebido. Se a chamada HTTPS não puder ser feita, uma exceção será gerada.

Permissões

Permissões de banco de dados

Requer a permissão de banco de dados EXECUTE ANY EXTERNAL ENDPOINT.

Por exemplo:

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

Habilitar no SQL Server 2025 e na Instância Gerenciada de SQL do Azure

Observação

O sp_invoke_external_rest_endpoint procedimento armazenado está em versão prévia para a versão prévia do SQL Server 2025 (17.x).

O sp_invoke_external_rest_endpoint procedimento armazenado está disponível na versão prévia do SQL Server 2025 (17.x) e na Instância Gerenciada de SQL do Azure configurada com a política de atualização always-up-to-date e está desabilitada por padrão.

Para habilitar o sp_invoke_external_rest_endpoint procedimento armazenado na versão prévia do SQL Server 2025 (17.x) e na Instância Gerenciada de SQL do Azure, execute o seguinte código T-SQL:

EXECUTE sp_configure 'external rest endpoint enabled', 1;

RECONFIGURE WITH OVERRIDE;

Para executar sp_configure para alterar uma opção de configuração ou para executar a instrução RECONFIGURE , um usuário deve receber a permissão de nível de servidor ALTER SETTINGS. A permissão ALTER SETTINGS é mantida implicitamente pelas funções de servidor fixas sysadmin e serveradmin.

Observação

sp_invoke_external_rest_endpoint é habilitado por padrão no Banco de Dados SQL do Azure e no Banco de Dados SQL no Fabric.

Formato de resposta

A resposta da chamada HTTP e os dados resultantes enviados de volta pelo ponto de extremidade invocado estão disponíveis por meio do parâmetro de saída @response . @response pode conter um documento JSON com o seguinte esquema:

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

Especificamente:

• response: um objeto JSON que contém o resultado HTTP e outros metadados de resposta.
• result: a carga JSON retornada pela chamada HTTP. Omitido se o resultado HTTP recebido for um 204 (No Content).

Ou o @response pode conter um documento XML com o seguinte esquema:

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

Especificamente:

• response: um objeto XML que contém o resultado HTTP e outros metadados de resposta.
• result: a carga XML retornada pela chamada HTTP. Omitido se o resultado HTTP recebido for um 204 (No Content).

response Na seção, além do código de status HTTP e da descrição, todo o conjunto de cabeçalhos de resposta recebidos são fornecidos no headers objeto. O exemplo a seguir mostra uma response seção em JSON (também a estrutura para respostas de texto):

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

E o exemplo a seguir mostra uma response seção em 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>

Pontos de extremidade permitidos

Importante

Essa lista se aplica apenas ao Banco de Dados SQL do Azure e à Instância Gerenciada de SQL do Azure.

Somente chamadas para pontos de extremidade para os seguintes serviços são permitidas:

Serviço do Azure	Domínio
Funções do Azure	*.azurewebsites.net
Serviço de Aplicativos do Azure	*.azurewebsites.net
Ambiente de Serviço de Aplicativo do Azure	*.appserviceenvironment.net
Aplicativos Web Estáticos do Azure	*.azurestaticapps.net
Aplicativos Lógicos do Azure	*.logic.azure.com
Hubs de eventos do Azure	*.servicebus.windows.net
Grade de Eventos do Azure	*.eventgrid.azure.net
Serviços de IA do Azure	*.cognitiveservices.azure.com *.api.cognitive.microsoft.com
OpenAI do Azure	*.openai.azure.com
PowerApps/Dataverse	*.api.crm.dynamics.com
Microsoft Dynamics	*.dynamics.com
Instâncias de Contêiner do Azure	*.azurecontainer.io
Aplicativos de Contêiner do Azure	*.azurecontainerapps.io
Power BI	api.powerbi.com
Gráfico da Microsoft	graph.microsoft.com
Serviços de análise	*.asazure.windows.net
IoT Central	*.azureiotcentral.com
Gerenciamento da API	*.azure-api.net
Armazenamento do Blobs do Azure	*.blob.core.windows.net
Arquivos do Azure	*.file.core.windows.net
Armazenamento de Filas do Azure	*.queue.core.windows.net
Armazenamento de Tabelas do Azure	*.table.core.windows.net
Serviços de Comunicação do Azure	*.communications.azure.com
Pesquisa do Bing	api.bing.microsoft.com
Cofre de Chave do Azure	*.vault.azure.net
IA do Azure Search	*.search.windows.net
Mapas do Azure	*.atlas.microsoft.com
Tradutor de IA do Azure	api.cognitive.microsofttranslator.com

As regras de firewall de saída para o Banco de Dados SQL do Azure e o mecanismo de controle do Azure Synapse Analytics podem ser usadas para restringir ainda mais o acesso de saída a pontos de extremidade externos.

Observação

Se você quiser invocar um serviço REST que não esteja dentro da lista de permissões, poderá usar o Gerenciamento de API para expor com segurança o serviço desejado e disponibilizá-lo para sp_invoke_external_rest_endpointo .

Limites

Tamanho da carga

A carga útil, tanto quando recebida quanto quando enviada, é codificada em UTF-8 quando enviada pela rede. Nesse formato, seu tamanho é limitado a 100 MB.

Comprimento da URL

O comprimento máximo da URL (gerado após o uso do parâmetro @url e a adição das credenciais especificadas à cadeia de caracteres de consulta, se houver) é de 8 KB; o comprimento máximo da cadeia de caracteres de consulta (cadeia de caracteres de consulta + cadeia de caracteres de consulta de credencial) é de 4 KB.

Tamanho dos cabeçalhos

O tamanho máximo do cabeçalho de solicitação e resposta (todos os campos de cabeçalho: cabeçalhos passados por meio @headers parâmetro + cabeçalho de credencial + cabeçalhos fornecidos pelo sistema) é de 8 KB.

Limitação

O número de conexões simultâneas com pontos de extremidade externos feitas por meio sp_invoke_external_rest_endpoint de é limitado a 10% dos threads de trabalho, com um máximo de 150 trabalhos. Em um único banco de dados , a limitação é imposta no nível do banco de dados, enquanto em um pool elástico a limitação é imposta no banco de dados e no nível do pool.

Para verificar quantas conexões simultâneas um banco de dados pode sustentar, execute a seguinte consulta:

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();

Se uma nova conexão com um ponto de extremidade externo usando sp_invoke_external_rest_endpoint for tentada quando as conexões simultâneas máximas já forem atingidas, o erro 10928 (ou 10936 se você tiver atingido os limites de pools elásticos) será gerado. Por exemplo:

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.

Credenciais

Alguns pontos de extremidade REST exigem autenticação para serem invocados corretamente. A autenticação geralmente pode ser feita passando alguns pares de valores-chave específicos na cadeia de caracteres de consulta ou nos cabeçalhos HTTP definidos com a solicitação.

É possível usar DATABASE SCOPED CREDENTIAL para armazenar com segurança os dados de autenticação (como um token de portador, por exemplo) a serem usados sp_invoke_external_rest_endpoint para chamar um ponto de extremidade protegido. Ao criar o DATABASE SCOPED CREDENTIALparâmetro, use o IDENTITY parâmetro para especificar quais dados de autenticação são passados para o ponto de extremidade invocado e como. IDENTITY dá suporte a quatro opções:

• HTTPEndpointHeaders: enviar dados de autenticação especificados usando os cabeçalhos de solicitação
• HTTPEndpointQueryString: enviar dados de autenticação especificados usando a String de Consulta
• Managed Identity: envie a Identidade Gerenciada Atribuída pelo Sistema usando os cabeçalhos da solicitação
• Shared Access Signature: fornecer acesso delegado limitado aos recursos por meio de uma URL assinada (também conhecida como SAS)

O criado DATABASE SCOPED CREDENTIAL pode ser usado por meio do parâmetro @credential :

EXECUTE 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>];

Cabeçalhos da solicitação

Com esse IDENTITY valor, o DATABASE SCOPED CREDENTIAL valor é adicionado aos cabeçalhos de solicitação. O par chave-valor que contém as informações de autenticação deve ser fornecido por meio do SECRET parâmetro usando um formato JSON simples. Por exemplo:

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

Cadeia de caracteres de consulta

Com esse IDENTITY valor, o DATABASE SCOPED CREDENTIAL valor é adicionado à cadeia de caracteres de consulta. O par chave-valor que contém as informações de autenticação deve ser fornecido por meio do SECRET parâmetro usando um formato JSON simples. Por exemplo:

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

Identidade Gerenciada

• Senha oferece autenticação com credenciais do Microsoft Entra
• Universal com MFA adiciona autenticação multifator
• O Integrated usa provedores de federação, como os Serviços de Federação do Active Directory (ADFS), para habilitar experiências de Logon Único (SSO)
• Entidade de serviço habilita a autenticação a partir de Aplicativos Azure
• Identidade Gerenciada habilita a autenticação de aplicativos atribuídos a identidades do Microsoft Entra

Com esse IDENTITY valor, as informações de autenticação são DATABASE SCOPED CREDENTIAL obtidas da identidade gerenciada atribuída pelo sistema do servidor lógico no qual o banco de dados reside e são passadas nos cabeçalhos de solicitação. Deve SECRET ser definido como o APP_ID (ou CLIENT_ID) usado para configurar a autenticação do Microsoft Entra do ponto de extremidade chamado. Para obter um exemplo, consulte Configurar seu Serviço de Aplicativo ou aplicativo do Azure Functions para usar a entrada do Microsoft Entra.

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

Há suporte para identidades gerenciadas atribuídas pelo sistema e pelo usuário:

• Se houver pelo menos uma identidade gerenciada atribuída pelo usuário, a identidade primária definida será usada para autenticação ao usar uma credencial no escopo do banco de dados baseada em identidade gerenciada.

• Se não houver nenhuma identidade gerenciada atribuída pelo usuário atribuída, a identidade gerenciada atribuída pelo sistema será usada, se estiver habilitada, para autenticação ao usar uma credencial com escopo de banco de dados baseada em identidade gerenciada.

• Se as identidades gerenciadas atribuídas pelo usuário e pelo sistema forem definidas, a identidade gerenciada atribuída pelo usuário será usada.

• Se houver mais de uma identidade gerenciada atribuída pelo usuário atribuída, somente a identidade primária será usada.

Regras de nome de credencial

A DATABASE SCOPED CREDENTIAL criada deve aderir a regras específicas para ser usada com sp_invoke_external_rest_endpointo . As regras são as seguintes:

• Deve ser um URL válido
• O domínio de URL deve ser um dos domínios incluídos na lista de permissões
• A URL não deve conter uma cadeia de caracteres de consulta
• Protocolo + FQDN (Nome de Domínio Totalmente Qualificado) da URL chamada deve corresponder ao Protocolo + FQDN do nome da credencial
• Cada parte do caminho de URL chamado deve corresponder completamente à respectiva parte do caminho de URL no nome da credencial
• A credencial deve apontar para um caminho mais genérico do que a URL da solicitação. Por exemplo, uma credencial criada para https://northwind.azurewebsite.net/customers path não pode ser usada para a URL https://northwind.azurewebsite.net

Regras de ordenação e nome de credencial

A Seção RFC 3986 6.2.2.1 afirma que "Quando um URI usa componentes da sintaxe genérica, as regras de equivalência de sintaxe do componente sempre se aplicam; ou seja, que o esquema e o host não diferenciam maiúsculas de minúsculas, e a Seção 2.7.3 da RFC 7230 menciona que "todos os outros são comparados de maneira diferenciada de maiúsculas de minúsculas".

Como há uma regra de ordenação definida no nível do banco de dados, a lógica a seguir é aplicada, para ser coerente com a regra de ordenação de banco de dados e com o RFC mencionado acima. (A regra descrita pode ser potencialmente mais restritiva do que as regras RFC, por exemplo, se o banco de dados estiver configurado para usar um agrupamento que diferencia maiúsculas de minúsculas.):

1. Verifique se a URL e a credencial correspondem usando o RFC, o que significa:
   • Verifique o esquema e o host usando uma ordenação que não diferencia maiúsculas de minúsculas (Latin1_General_100_CI_AS_KS_WS_SC)
   • Verifique se todos os outros segmentos do URL são comparados em um agrupamento que diferencia maiúsculas de minúsculas (Latin1_General_100_BIN2)
2. Verifique se a URL e a credencial correspondem usando as regras de agrupamento do banco de dados (e sem fazer nenhuma codificação de URL).

Conceder permissões para usar credencial

Os usuários do banco de dados que acessam uma DATABASE SCOPED CREDENTIAL devem ter permissão para usar essa credencial.

Para usar a credencial, um usuário do banco de dados deve ter REFERENCES permissão em uma credencial específica:

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

Comentários

Tipo de espera

Quando sp_invoke_external_rest_endpoint está aguardando a conclusão da chamada para o serviço invocado, ele relata um HTTP_EXTERNAL_CONNECTION tipo de espera.

HTTPS e TLS

Há suporte apenas para pontos de extremidade configurados para usar HTTPS com protocolo de criptografia TLS.

Redirecionamentos HTTP

sp_invoke_external_rest_endpoint não segue automaticamente qualquer redirecionamento HTTP recebido como uma resposta do ponto de extremidade invocado.

Cabeçalhos HTTP

sp_invoke_external_rest_endpoint injeta automaticamente os seguintes cabeçalhos na solicitação HTTP:

• tipo de conteúdo: definido como application/json; charset=utf-8
• aceitar: defina como application/json
• user-agent: defina <EDITION>/<PRODUCT VERSION> , por exemplo: SQL Azure/12.0.2000.8

Embora o agente do usuário seja sempre substituído pelo procedimento armazenado, os valores de cabeçalho de tipo de conteúdo e de aceitação podem ser definidos pelo usuário por meio do parâmetro @headers . Somente a diretiva de tipo de mídia pode ser especificada no tipo de conteúdo e não é possível especificar as diretivas charset ou boundary.

Tipos de mídia compatíveis com carga de solicitação e resposta

A seguir estão os valores aceitos para o tipo de conteúdo do cabeçalho.

• aplicativo/json
• application/vnd.microsoft.*.json
• aplicativo/xml
• application/vnd.microsoft.*.xml
• application/vnd.microsoft.*+xml
• Application/x-www-form-urlencoded
• Texto/*

Para o cabeçalho accept , a seguir estão os valores aceitos.

• aplicativo/json
• aplicativo/xml
• Texto/*

Para obter mais informações sobre tipos de cabeçalho de texto, consulte o registro de tipo de texto no IANA.

Observação

Se você estiver testando a invocação do ponto de extremidade REST com outras ferramentas, como cURL ou qualquer cliente REST moderno, como o Insomnia, certifique-se de incluir os mesmos cabeçalhos que são injetados automaticamente para sp_invoke_external_rest_endpoint ter o mesmo comportamento e resultados.

Práticas recomendadas

Usar uma técnica de envio em lote

Se você precisar enviar um conjunto de linhas para um ponto de extremidade REST, por exemplo, para uma Função do Azure ou para um hub de eventos, é recomendável agrupar as linhas em um único documento JSON, para evitar a sobrecarga de chamada HTTPS para cada linha enviada. Isso pode ser feito usando a FOR JSON instrução, por exemplo:

-- 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 AS INT, @response AS NVARCHAR (MAX);

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

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

Exemplos

Aqui você pode encontrar alguns exemplos sobre como usar sp_invoke_external_rest_endpoint a integração com serviços comuns do Azure, como Azure Functions ou Hubs de Eventos do Azure. Mais exemplos para integração com outros serviços podem ser encontrados no GitHub.

R. Chamar uma função do Azure usando uma associação de gatilho HTTP sem autenticação

O exemplo a seguir chama uma Função do Azure usando uma associação de gatilho HTTP que permite acesso anônimo.

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

EXECUTE
    @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. Chamar uma função do Azure usando uma associação de gatilho HTTP com uma chave de autorização

O exemplo a seguir chama uma Função do Azure usando uma associação de gatilho HTTP configurada para exigir uma chave de autorização. A chave de autorização é passada no x-function-key cabeçalho conforme exigido pelo Azure Functions. Para obter mais informações, consulte Azure Functions – autorização de chave de 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 AS INT, @response AS NVARCHAR (MAX);

EXECUTE
    @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. Ler o conteúdo de um arquivo do Armazenamento de Blobs do Azure com um token SAS

Este exemplo lê um arquivo do Armazenamento de Blobs do Azure usando um token SAS para autenticação. Os resultados são retornados em XML, portanto, você deve usar o cabeçalho "Accept":"application/xml".

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

EXECUTE
    @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. Enviar uma mensagem para um hub de eventos usando a Identidade Gerenciada do Banco de Dados SQL do Azure

Este exemplo mostra como você pode enviar mensagens para Hubs de Eventos usando a Identidade Gerenciada de SQL do Azure. Verifique se você configurou a Identidade Gerenciada do Sistema para o servidor lógico do Banco de Dados SQL do Azure que hospeda seu banco de dados, por exemplo:

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

Depois disso, configure os Hubs de Eventos para permitir que a Identidade Gerenciada do SQL Server do Azure possa enviar mensagens (função "Remetente de Dados dos Hubs de Eventos do Azure") para o hub de eventos desejado. Para obter mais informações, consulte Usar Hubs de Eventos com identidades gerenciadas.

Depois que isso for feito, você poderá usar o nome da Managed Identity identidade ao definir a credencial no escopo do banco de dados usada por sp_invoke_external_rest_endpoint. Conforme explicado em Autenticar um aplicativo com a ID do Microsoft Entra para acessar os recursos dos Hubs de Eventos, o nome do recurso (ou ID) a ser usado ao usar a autenticação do 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 AS UNIQUEIDENTIFIER = NEWID();

DECLARE @payload AS NVARCHAR (MAX) = (SELECT *
    FROM (VALUES (@Id, 'John', 'Doe')) AS UserTable(UserId, FirstName, LastName)
    FOR JSON AUTO, WITHOUT_ARRAY_WRAPPER);

DECLARE @url AS NVARCHAR (4000) = 'https://<EVENT-HUBS-NAME>.servicebus.windows.net/from-sql/messages';

DECLARE @headers AS NVARCHAR (4000) = N'{"BrokerProperties": "'
    + STRING_ESCAPE('{"PartitionKey": "'
    + CAST (@Id AS NVARCHAR (36)) + '"}', 'json') + '"}';

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

EXECUTE
    @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. Ler e gravar um arquivo no Armazenamento de Arquivos do Azure com credenciais no escopo do Banco de Dados SQL do Azure

Este exemplo grava um arquivo em um Armazenamento de Arquivos do Azure usando credenciais no escopo do Banco de Dados SQL do Azure para autenticação e retorna o conteúdo. Os resultados são retornados em XML, portanto, você deve usar o cabeçalho "Accept":"application/xml".

Comece criando uma chave mestra para o banco de dados SQL do Azure. Substitua por <password> uma senha forte.

CREATE MASTER KEY ENCRYPTION BY PASSWORD = '<password>';
GO

Em seguida, crie as credenciais no escopo do banco de dados usando o token SAS fornecido pela Conta de Armazenamento de Blobs do Azure. Substitua <token> pelo token SAS fornecido.

CREATE DATABASE SCOPED CREDENTIAL [filestore]
WITH IDENTITY = 'SHARED ACCESS SIGNATURE', SECRET = '<token>';
GO

Em seguida, crie o arquivo e adicione texto a ele com as duas instruções a seguir. Substitua <domain> pelo caminho apropriado.

DECLARE @payload AS NVARCHAR (MAX) = (SELECT *
    FROM (VALUES ('Hello from Azure SQL!', sysdatetime())) AS payload([message], [timestamp])
    FOR JSON AUTO, WITHOUT_ARRAY_WRAPPER);

DECLARE @response AS NVARCHAR (MAX);
DECLARE @url AS NVARCHAR (MAX);
DECLARE @headers AS NVARCHAR (1000);

DECLARE @len AS INT = len(@payload);

-- Create the file
SET @url = 'https://<domain>.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');

EXECUTE 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://<domain>.file.core.windows.net/myfiles/test-me-from-azure-sql.json';
SET @url += '?comp=range';

EXECUTE sp_invoke_external_rest_endpoint
    @url = @url,
    @method = 'PUT',
    @headers = @headers,
    @payload = @payload,
    @credential = [filestore],
    @response = @response OUTPUT;

SELECT CAST (@response AS XML);
GO

Por fim, use a instrução a seguir para ler o arquivo. Substitua <domain> pelo caminho apropriado.

DECLARE @response AS NVARCHAR (MAX);

DECLARE @url AS NVARCHAR (MAX) = 'https://<domain>.file.core.windows.net/myfiles/test-me-from-azure-sql.json';

EXECUTE sp_invoke_external_rest_endpoint
    @url = @url,
    @headers = '{"Accept":"application/xml"}',
    @credential = [filestore],
    @method = 'GET',
    @response = @response OUTPUT;

SELECT CAST (@response AS XML);
GO

F. Chamar um Azure OpenAI usando a Identidade Gerenciada

O exemplo a seguir chama um modelo do Azure OpenAI usando identidades gerenciadas no Microsoft Entra para SQL do Azure. Substitua <my-azure-openai-endpoint> e <model-deployment-name> pelo seu ponto de extremidade e nome de modelo do Azure OpenAI, respectivamente, e verifique se você deu à Identidade Gerenciada a função de usuário openai dos Serviços Cognitivos no serviço Azure OpenAI.

CREATE DATABASE SCOPED CREDENTIAL [https://<my-azure-openai-endpoint>.openai.azure.com]
    WITH IDENTITY = 'Managed Identity', SECRET = '{"resourceid":"https://cognitiveservices.azure.com"}';
GO

DECLARE @response AS NVARCHAR (MAX);

DECLARE @payload AS NVARCHAR (MAX) = JSON_OBJECT('input':'hello world');

EXECUTE sp_invoke_external_rest_endpoint
    @url = 'https://<my-azure-openai-endpoint>.openai.azure.com/openai/deployments/<model-deployment-name>/embeddings?api-version=2024-08-01-preview',
    @method = 'POST',
    @credential = [https://<my-azure-openai-endpoint>.openai.azure.com],
    @payload = @payload,
    @response = @response OUTPUT;

SELECT json_query(@response, '$.result.data[0].embedding'); -- Assuming the called model is an embedding model

Conteúdo relacionado

• Gerenciamento de recursos no Banco de dados SQL do Azure
• sys.dm_resource_governor_resource_pools_history_ex
• sys.dm_resource_governor_workload_groups_history_ex
• sys.dm_user_db_resource_governance
• Permissões de banco de dados GRANT (Transact-SQL)
• CREATE DATABASE SCOPED CREDENTIAL (Transact-SQL)
• Gerenciamento da API
• sp_invoke_external_rest_endpoint exemplos de uso