sp_invoke_external_rest_endpoint (T-SQL)

Berlaku untuk: Azure SQL Database

Prosedur sp_invoke_external_rest_endpoint tersimpan memanggil titik akhir HTTPS REST yang disediakan sebagai argumen input ke prosedur.

Sintaks

Konvensi sintaks 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 ]

Argumen

[ @url = ] N'url'

URL titik akhir HTTPS REST yang akan dipanggil. @url adalah nvarchar(4000) tanpa default.

[ @payload = ] N'request_payload'

String Unicode dalam format JSON, XML, atau TEXT yang berisi payload untuk dikirim ke titik akhir HTTPS REST. Payload harus berupa dokumen JSON yang valid, dokumen XML yang terbentuk dengan baik, atau teks. @payload adalah nvarchar(max) tanpa default.

[ @headers = ] N'headers'

Header yang harus dikirim sebagai bagian dari permintaan ke titik akhir HTTPS REST. Header harus ditentukan menggunakan format JSON datar (dokumen JSON tanpa struktur berlapis). Header yang ditentukan dalam daftar nama header Terlarang akan diabaikan bahkan jika secara eksplisit diteruskan dalam parameter @headers ; nilainya akan dibuang atau diganti dengan nilai yang disediakan sistem saat memulai permintaan HTTPS.

Parameter @headers adalah nvarchar(4000) tanpa default.

[ @method = ] N'method'

Metode HTTP untuk memanggil URL. Harus salah satu nilai berikut: GET, , POST, PUT, PATCH, DELETE, HEAD. @method adalah nvarchar(6) dengan POST sebagai nilai default.

[ @timeout = ] detik

Waktu dalam detik yang diizinkan agar panggilan HTTPS berjalan. Jika permintaan dan respons HTTP lengkap tidak dapat dikirim dan diterima dalam batas waktu yang ditentukan dalam hitungan detik, eksekusi prosedur tersimpan dihentikan, dan pengecualian dinaikkan. Waktu habis dimulai ketika koneksi HTTP dimulai dan berakhir ketika respons, dan payload disertakan jika ada, telah diterima. @timeout adalah smallint positif dengan nilai default 30. Nilai yang diterima: 1 hingga 230.

[ @credential = ] kredensial

Menunjukkan objek KREDENSIAL LINGKUP DATABASE mana yang digunakan untuk menyuntikkan info autentikasi dalam permintaan HTTPS. @credential adalah sysname tanpa nilai default.

@response HASIL

Izinkan respons yang diterima dari titik akhir yang disebut untuk diteruskan ke variabel yang ditentukan. @response adalah nvarchar(maks).

Nilai hasil

Eksekusi akan kembali 0 jika panggilan HTTPS dilakukan dan kode status HTTP yang diterima adalah kode status 2xx (Success). Jika kode status HTTP yang diterima tidak berada dalam rentang 2xx, nilai pengembalian akan menjadi kode status HTTP yang diterima. Jika panggilan HTTPS tidak dapat dilakukan sama sekali, pengecualian akan dilemparkan.

Izin

Memerlukan izin DATABASE EXECUTE ANY EXTERNAL ENDPOINT.

Contohnya:

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

Format respons

Respons panggilan HTTP dan data yang dihasilkan yang dikirim kembali oleh titik akhir yang dipanggil tersedia melalui parameter output @response . @response mungkin berisi dokumen JSON dengan skema berikut:

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

Khususnya:

• respons: objek JSON yang berisi hasil HTTP dan metadata respons lainnya.
• hasil: payload JSON yang dikembalikan oleh panggilan HTTP. Dihilangkan jika hasil HTTP yang diterima adalah 204 (No Content).

Atau @response mungkin berisi dokumen XML dengan skema berikut:

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

Khususnya:

• respons: objek XML yang berisi hasil HTTP dan metadata respons lainnya.
• hasil: payload XML yang dikembalikan oleh panggilan HTTP. Dihilangkan jika hasil HTTP yang diterima adalah 204 (No Content).

Di bagian , response selain dari kode status HTTP dan deskripsi, seluruh set header respons yang diterima akan disediakan dalam headers objek. Contoh berikut menunjukkan response bagian di JSON (juga struktur untuk respons teks):

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

Dan contoh berikut menunjukkan response bagian di 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>

Titik akhir yang diizinkan

Hanya panggilan ke titik akhir dalam layanan berikut yang diizinkan:

Layanan Azure	Domain
Azure Functions	*.azurewebsites.net
Azure Apps Service	*.azurewebsites.net
Lingkungan Azure App Service	*.appserviceenvironment.net
Azure Static Web Apps	*.azurestaticapps.net
Azure Logic Apps	*.logic.azure.com
Azure Event Hubs	*.servicebus.windows.net
Kisi Aktivitas Azure	*.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 Pusat	*.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
Penyimpanan Tabel Azure	*.table.core.windows.net
Azure Communication Services	*.communications.azure.com
Pencarian Bing	api.bing.microsoft.com
Azure Key Vault	*.vault.azure.net
Pencarian Azure AI	*.search.windows.net
Azure Maps	*.atlas.microsoft.com
Penerjemah Azure AI	api.cognitive.microsofttranslator.com

Aturan firewall keluar untuk Azure SQL Database dan mekanisme kontrol Azure Synapse Analytics dapat digunakan untuk lebih membatasi akses keluar ke titik akhir eksternal.

Catatan

Jika Anda ingin memanggil layanan REST yang tidak berada dalam daftar yang diizinkan, Anda dapat menggunakan API Management untuk mengekspos layanan yang diinginkan dengan aman dan membuatnya tersedia untuk sp_invoke_external_rest_endpoint.

Batas

Besar payload

Payload, baik ketika diterima maupun saat dikirim, dikodekan UTF-8 saat dikirim melalui kawat. Dalam format itu, ukurannya dibatasi hingga 100 MB.

Panjang URL

Panjang URL maksimum (dihasilkan setelah menggunakan parameter @url dan menambahkan kredensial yang ditentukan ke string kueri, jika ada) adalah 8 KB; panjang string kueri maksimum (string kueri + string kueri info masuk) adalah 4 KB.

Ukuran header

Ukuran header permintaan dan respons maksimum (semua bidang header: header yang diteruskan melalui parameter @headers + header kredensial + header yang disediakan sistem) adalah 8 KB.

Pembatasan

Jumlah koneksi bersamaan ke titik akhir eksternal yang dilakukan melalui sp_invoke_external_rest_endpoint dibatasi hingga 10% utas pekerja, dengan maksimum 150 pekerja. Pada pembatasan database tunggal diberlakukan pada tingkat database, sementara pada pembatasan kumpulan elastis diberlakukan baik di database maupun di tingkat kumpulan.

Untuk memeriksa berapa banyak koneksi bersamaan yang dapat dipertahankan database, jalankan kueri berikut:

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

Jika koneksi baru ke titik akhir eksternal yang menggunakan sp_invoke_external_rest_endpoint dicoba ketika koneksi bersamaan maksimum sudah tercapai, kesalahan 10928 (atau 10936 jika Anda telah mencapai batas kumpulan elastis) akan dinaikkan. Contohnya:

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.

Informasi Masuk

Beberapa titik akhir REST memerlukan autentikasi agar dapat dipanggil dengan benar. Autentikasi biasanya dapat dilakukan dengan meneruskan beberapa pasangan kunci-nilai tertentu dalam string kueri atau di header HTTP yang diatur dengan permintaan.

Dimungkinkan untuk menggunakan KREDENSIAL CAKUPAN DATABASE untuk menyimpan data autentikasi dengan aman (seperti token Pembawa misalnya) untuk digunakan oleh sp_invoke_external_rest_endpoint untuk memanggil titik akhir yang dilindungi. Saat membuat KREDENSIAL CAKUPAN DATABASE, gunakan parameter IDENTITY untuk menentukan data autentikasi apa yang akan diteruskan ke titik akhir yang dipanggil dan bagaimana. IDENTITY mendukung empat opsi:

• HTTPEndpointHeaders: kirim data autentikasi yang ditentukan menggunakan Header Permintaan
• HTTPEndpointQueryString: mengirim data autentikasi yang ditentukan menggunakan String Kueri
• Managed Identity: kirim Identitas Terkelola yang Ditetapkan Sistem menggunakan header permintaan
• Shared Access Signature: menyediakan akses yang didelegasikan terbatas ke sumber daya melalui URL yang ditandatangani (Juga disebut sebagai SAS)

KREDENSIAL CAKUPAN DATABASE yang dibuat dapat digunakan melalui parameter @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>]

Minta Header

Dengan nilai IDENTITY ini, KREDENSIAL LINGKUP DATABASE akan ditambahkan ke header permintaan. Pasangan kunci-nilai yang berisi informasi autentikasi harus disediakan melalui parameter SECRET menggunakan format JSON datar. Contohnya:

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

String Kueri

Dengan nilai IDENTITY ini, KREDENSIAL CAKUPAN DATABASE akan ditambahkan ke string kueri. Pasangan kunci-nilai yang berisi informasi autentikasi harus disediakan melalui parameter SECRET menggunakan format JSON datar. Contohnya:

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

Identitas Terkelola

• Kata sandi menawarkan autentikasi dengan kredensial Microsoft Entra
• Universal dengan MFA menambahkan autentikasi multifaktor
• Terintegrasi menggunakan penyedia federasi seperti Layanan Federasi Direktori Aktif (ADFS) untuk mengaktifkan pengalaman Akses Menyeluruh (SSO)
• Perwakilan Layanan memungkinkan autentikasi dari aplikasi Azure
• Identitas Terkelola memungkinkan autentikasi dari aplikasi yang ditetapkan identitas Microsoft Entra

Dengan nilai IDENTITY ini, informasi autentikasi untuk DATABASE SCOPED CREDENTIAL diambil dari identitas terkelola yang ditetapkan sistem dari server logis tempat database berada, dan diteruskan di header permintaan. SECRET harus diatur ke APP_ID (atau CLIENT_ID) yang digunakan untuk mengonfigurasi autentikasi Microsoft Entra dari titik akhir yang disebut. (Misalnya: Mengonfigurasi App Service atau aplikasi Azure Functions Anda untuk menggunakan masuk Microsoft Entra)

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

Identitas terkelola yang ditetapkan sistem dan yang ditetapkan pengguna didukung:

• Jika setidaknya ada satu identitas terkelola yang ditetapkan pengguna, identitas utama yang ditentukan digunakan untuk autentikasi saat menggunakan kredensial cakupan database berbasis identitas terkelola.

• Jika tidak ada identitas terkelola yang ditetapkan pengguna yang ditetapkan, identitas terkelola yang ditetapkan sistem akan digunakan, jika diaktifkan, untuk autentikasi saat menggunakan kredensial cakupan database berbasis identitas terkelola.

• Jika identitas terkelola yang ditetapkan pengguna dan yang ditetapkan sistem ditentukan, identitas terkelola yang ditetapkan pengguna akan digunakan.

• Jika ada lebih dari satu identitas terkelola yang ditetapkan pengguna yang ditetapkan, hanya identitas utama yang digunakan.

Aturan nama kredensial

KREDENSIAL CAKUPAN DATABASE yang dibuat harus mematuhi aturan tertentu agar dapat digunakan dengan sp_invoke_external_rest_endpoint. Aturannya adalah sebagai berikut:

• Harus berupa URL yang valid
• Domain URL harus menjadi salah satu domain yang disertakan dalam daftar izin
• URL tidak boleh berisi string kueri
• Protokol + Nama Domain yang Sepenuhnya Memenuhi Syarat (FQDN) dari URL yang disebut harus cocok dengan Protokol + FQDN dari nama kredensial
• Setiap bagian dari jalur URL yang disebut harus sama sepenuhnya dengan bagian masing-masing jalur URL dalam nama kredensial
• Info masuk harus menunjuk ke jalur yang lebih umum daripada URL permintaan. Misalnya, kredensial yang dibuat untuk jalur https://northwind.azurewebsite.net/customers tidak dapat digunakan untuk URL https://northwind.azurewebsite.net

Aturan nama kolase dan kredensial

RFC 3986 Bagian 6.2.2.1 menyatakan bahwa "Ketika URI menggunakan komponen sintaksis generik, aturan kesetaraan sintaks komponen selalu berlaku; yaitu, bahwa skema dan host tidak peka huruf besar/kecil", dan RFC 7230 Bagian 2.7.3 menyebutkan bahwa "semua lainnya dibandingkan dengan cara yang peka huruf besar/kecil".

Karena ada aturan kolase yang ditetapkan di tingkat database, logika berikut akan diterapkan, agar koheren dengan aturan kolektasi database dan RFC yang disebutkan di atas. (Aturan yang dijelaskan berpotensi lebih ketat daripada aturan RFC, misalnya jika database diatur untuk menggunakan kolase peka huruf besar/kecil.):

1. Periksa apakah URL dan kredensial cocok menggunakan RFC, yang berarti:
   • Periksa skema dan host menggunakan kolater yang tidak peka huruf besar/kecil (Latin1_General_100_CI_AS_KS_WS_SC)
   • Periksa semua segmen URL lainnya dibandingkan dalam kolaset peka huruf besar/kecil (Latin1_General_100_BIN2)
2. Periksa apakah URL dan kecocokan kredensial menggunakan aturan kolase database (dan tanpa melakukan pengodean URL apa pun).

Memberikan izin untuk menggunakan info masuk

Pengguna database yang mengakses KREDENSIAL CAKUPAN DATABASE harus memiliki izin untuk menggunakan kredensial tersebut.

Untuk menggunakan kredensial, pengguna database harus memiliki REFERENCES izin pada kredensial tertentu:

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

Keterangan

Jenis tunggu

Ketika sp_invoke_external_rest_endpoint menunggu panggilan ke layanan yang dipanggil selesai, panggilan akan melaporkan jenis tunggu HTTP_EXTERNAL_CONNECTION.

HTTPS dan TLS

Hanya titik akhir yang dikonfigurasi untuk menggunakan HTTPS dengan setidaknya protokol enkripsi TLS 1.2 yang didukung.

Pengalihan HTTP

sp_invoke_external_rest_endpoint tidak akan secara otomatis mengikuti pengalihan HTTP yang diterima sebagai respons dari titik akhir yang dipanggil.

Header HTTP

sp_invoke_external_rest_endpoint akan secara otomatis menyuntikkan header berikut dalam permintaan HTTP:

• jenis konten: diatur ke application/json; charset=utf-8
• terima: atur ke application/json
• user-agent: set <EDITION>/<PRODUCT VERSION> misalnya: SQL Azure/12.0.2000.8

Meskipun agen pengguna akan selalu ditimpa oleh prosedur tersimpan, nilai header jenis konten dan terima dapat ditentukan pengguna melalui parameter @headers . Hanya direktif jenis media yang diizinkan untuk ditentukan dalam jenis konten dan menentukan arahan charset atau batas tidak dimungkinkan.

Jenis media yang didukung payload permintaan dan respons

Berikut ini adalah nilai yang diterima untuk jenis konten header.

• application/json
• application/vnd.microsoft.*.json
• application/xml
• application/vnd.microsoft.*.xml
• application/vnd.microsoft.*+xml
• application/x-www-form-urlencoded
• Teks/*

Untuk header terima, berikut ini adalah nilai yang diterima.

• application/json
• application/xml
• Teks/*

Untuk informasi selengkapnya tentang jenis header teks, lihat registri jenis teks di IANA.

Catatan

Jika Anda menguji pemanggilan titik akhir REST dengan alat lain, seperti cURL atau klien REST modern seperti Insomnia, pastikan untuk menyertakan header yang sama yang secara otomatis disuntikkan oleh sp_invoke_external_rest_endpoint untuk memiliki perilaku dan hasil yang sama.

Praktik terbaik

Menggunakan teknik batching

Jika Anda harus mengirim sekumpulan baris ke titik akhir REST, misalnya ke Azure Function atau ke pusat aktivitas, disarankan untuk mengumpulkan baris ke dalam satu dokumen JSON, untuk menghindari overhead panggilan HTTPS untuk setiap baris yang dikirim. Ini dapat dilakukan menggunakan FOR JSON pernyataan, misalnya:

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

Contoh

Di sini Anda dapat menemukan beberapa contoh tentang cara menggunakan sp_invoke_external_rest_endpoint untuk berintegrasi dengan Layanan Azure umum seperti Azure Functions atau Azure Event Hubs. Lebih banyak sampel untuk diintegrasikan dengan layanan lain dapat ditemukan di GitHub.

J. Memanggil Fungsi Azure menggunakan pengikatan pemicu HTTP tanpa autentikasi

Contoh berikut memanggil Azure Function menggunakan pengikatan pemicu HTTP yang memungkinkan akses anonim.

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. Memanggil Azure Function menggunakan pengikatan pemicu HTTP dengan kunci otorisasi

Contoh berikut memanggil Azure Function menggunakan pengikatan pemicu HTTP yang dikonfigurasi untuk memerlukan kunci otorisasi. Kunci otorisasi akan diteruskan di header seperti yang x-function-key diperlukan oleh Azure Functions. Untuk informasi selengkapnya, lihat Azure Functions - Otorisasi kunci 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. Membaca konten file dari Azure Blob Storage dengan token SAS

Contoh ini membaca file dari Azure Blob Storage menggunakan token SAS untuk autentikasi. Hasilnya akan dikembalikan dalam XML, jadi menggunakan header "Accept":"application/xml" akan diperlukan.

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. Mengirim pesan ke pusat aktivitas menggunakan Identitas Terkelola Azure SQL Database

Sampel ini memperlihatkan bagaimana Anda dapat mengirim pesan ke Azure Event Hubs menggunakan Azure SQL Managed Identity. Pastikan Anda telah mengonfigurasi Identitas Terkelola Sistem untuk server logis Azure SQL Database yang menghosting database Anda, misalnya:

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

Setelah itu, konfigurasikan Azure Event Hubs untuk memungkinkan Identitas Terkelola Azure SQL Server dapat mengirim pesan (peran "Pengirim Data Azure Event Hubs") ke hub peristiwa yang diinginkan. Untuk informasi selengkapnya, lihat Menggunakan Azure Event Hubs dengan identitas terkelola.

Setelah ini selesai, Anda dapat menggunakan Managed Identity nama identitas saat menentukan kredensial cakupan database yang akan digunakan oleh sp_invoke_external_rest_endpoint. Seperti yang dijelaskan dalam Mengautentikasi aplikasi dengan ID Microsoft Entra untuk mengakses sumber daya Event Hubs, nama sumber daya (atau ID) yang akan digunakan saat menggunakan autentikasi Microsoft Entra adalah 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. Membaca dan menulis file ke Azure File Storage dengan kredensial cakupan Azure SQL Database

Contoh ini menulis file ke Azure File Storage menggunakan kredensial cakupan Azure SQL Database untuk autentikasi lalu mengembalikan konten. Hasilnya akan dikembalikan dalam XML, jadi menggunakan header "Accept":"application/xml" akan diperlukan.

Mulailah dengan membuat kunci master untuk Azure SQL Database

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

Kemudian, buat kredensial cakupan database menggunakan token SAS yang disediakan oleh Akun Azure Blob Storage.

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

Selanjutnya, buat file dan tambahkan teks ke dalamnya dengan dua pernyataan berikut:

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

Terakhir, gunakan pernyataan berikut untuk membaca file

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

Konten terkait

• Manajemen sumber daya di Azure SQL Database
• sys.dm_resource_governor_resource_pools_history_ex
• sys.dm_resource_governor_resource_pools_history_ex
• sys.dm_user_db_resource_governance
• IZIN GRANT Database (Transact-SQL)
• MEMBUAT KREDENSIAL CAKUPAN DATABASE (Transact-SQL)
• API Management
• sp_invoke_external_rest_endpoint sampel penggunaan