Bagikan melalui

sp_invoke_external_rest_endpoint (Transact-SQL)

Berlaku untuk: Database SQL SQL Server 2025 (17.x) Azure SQL DatabaseAzure SQL Managed Instancedi Microsoft Fabric

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

Note

Prosedur sp_invoke_external_rest_endpoint tersimpan dalam pratinjau untuk SQL Server 2025 (17.x).

Cara untuk mengurangi risiko akses atau transfer data yang tidak sah

Caution

Menggunakan prosedur tersimpan sp_invoke_external_rest_endpoint memungkinkan transfer data ke entitas eksternal.

Untuk mengurangi risiko akses atau transfer data yang tidak sah, pertimbangkan praktik terbaik keamanan berikut:

  • Terapkan kontrol akses yang kuat: Pastikan hanya pengguna yang berwenang yang memiliki akses ke data sensitif dan titik akhir REST API. Gunakan prinsip hak istimewa paling sedikit, serta peran dan hak istimewa database.
  • Autentikasi dan otorisasi yang tepat: Pastikan bahwa semua panggilan REST diautentikasi dan diotorisasi untuk mencegah akses yang tidak sah.
  • Memantau dan mengaudit akses: Memantau dan mengaudit akses secara teratur ke database dan panggilan REST API untuk mendeteksi aktivitas yang mencurigakan.
  • Penilaian Keamanan Reguler: Melakukan penilaian keamanan reguler dan pemindaian kerentanan untuk mengidentifikasi dan mengurangi potensi risiko.
  • Pelatihan karyawan: Mendidik karyawan tentang risiko eksfiltrasi data dan pentingnya protokol keamanan berikut.

Syntax

Konvensi sintaks 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 ]
  [ , [ @retry_count = ] # of retries if there are errors ]

Arguments

[ @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 diabaikan meskipun secara eksplisit diteruskan dalam parameter @headers ; nilainya 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.

Jika parameter @retry_count ditentukan, parameter @timeout bertindak sebagai batas waktu kumulatif untuk prosedur.

[ @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).

[ @retry_count = ] # percobaan ulang jika ada kesalahan

Menentukan berapa kali prosedur tersimpan mencoba kembali menyambungkan ke titik akhir yang ditentukan jika ada kesalahan. @retry_count adalah tinyint positif dengan nilai default 0. Nilai yang diterima: 0 hingga 10, dengan 0 melewati semua logika coba lagi. Interval coba lagi ditentukan menggunakan Retry-After header jika ada. Jika header tidak ada, sistem menerapkan strategi backoff eksponensial untuk kode kesalahan tertentu. Dalam semua kasus lain, penundaan default 200 milidetik digunakan.

Mengembalikan nilai

Eksekusi mengembalikan 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 yang dikembalikan adalah kode status HTTP yang diterima. Jika panggilan HTTPS tidak dapat dilakukan sama sekali, pengecualian akan dilemparkan.

Permissions

Izin database

Memerlukan izin DATABASE EXECUTE ANY EXTERNAL ENDPOINT.

Contohnya:

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

Aktifkan di SQL Server 2025 dan Azure SQL Managed Instance

Note

Prosedur sp_invoke_external_rest_endpoint tersimpan dalam pratinjau untuk SQL Server 2025 (17.x).

Prosedur sp_invoke_external_rest_endpoint tersimpan tersedia di SQL Server 2025 (17.x) dan Azure SQL Managed Instance dengan kebijakan pembaruan SQL Server 2025 atau Always-up-to-date dan dinonaktifkan secara default.

Untuk mengaktifkan sp_invoke_external_rest_endpoint prosedur tersimpan di SQL Server 2025 (17.x) dan Azure SQL Managed Instance, jalankan kode T-SQL berikut:

EXECUTE sp_configure 'external rest endpoint enabled', 1;

RECONFIGURE WITH OVERRIDE;

Untuk menjalankan sp_configure untuk mengubah opsi konfigurasi atau menjalankan pernyataan KONFIGURASI ULANG , pengguna harus diberikan izin tingkat server ALTER SETTINGS. Izin UBAH PENGATURAN secara implisit dipegang oleh peran server tetap sysadmin dan serveradmin.

Note

sp_invoke_external_rest_endpoint diaktifkan secara default di Azure SQL Database dan database SQL di Fabric.

Format Tanggapan

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

Specifically:

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

Specifically:

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

Important

Daftar ini hanya berlaku untuk Azure SQL Database dan Azure SQL Managed Instance.

Hanya panggilan ke titik akhir untuk layanan berikut yang diizinkan:

Layanan Azure Domain
Azure Functions *.azurewebsites.net
Layanan Aplikasi Azure *.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
Azure Event Grid *.eventgrid.azure.net
Layanan Azure AI *.cognitiveservices.azure.com
*.api.cognitive.microsoft.com
Azure OpenAI *.openai.azure.com
PowerApps / Dataverse *.api.crm.dynamics.com
Dinamika Microsoft *.dynamics.com
Azure Container Instances *.azurecontainer.io
Azure Container Apps *.azurecontainerapps.io
Power BI api.powerbi.com
Microsoft Graph graph.microsoft.com
Analysis Services *.asazure.windows.net
IoT Central *.azureiotcentral.com
API Management *.azure-api.net
Azure Blob Storage *.blob.core.windows.net
Azure Files *.file.core.windows.net
Azure Queue Storage *.queue.core.windows.net
Penyimpanan Tabel Azure *.table.core.windows.net
Azure Communication Services *.communications.azure.com
Bing Search api.bing.microsoft.com
Azure Key Vault *.vault.azure.net
Pencarian Azure AI *.search.windows.net
Azure Maps *.atlas.microsoft.com
Azure AI Penerjemah 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.

Note

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.

Limits

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

Throttling

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) dimunculkan. 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.

Credentials

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 DATABASE SCOPED CREDENTIAL 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 DATABASE SCOPED CREDENTIAL, gunakan IDENTITY parameter untuk menentukan data autentikasi apa yang 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)

Yang dibuat DATABASE SCOPED CREDENTIAL dapat digunakan melalui parameter @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>];

Dengan nilai ini IDENTITY , DATABASE SCOPED CREDENTIAL ditambahkan ke header permintaan. Pasangan kunci-nilai yang berisi informasi autentikasi harus disediakan melalui SECRET parameter 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>"}';

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

Remarks

Jenis tunggu

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

HTTPS dan TLS

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

Pengalihan HTTP

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

Header HTTP

sp_invoke_external_rest_endpoint 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 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
  • text/*

Untuk header terima, berikut ini adalah nilai yang diterima.

  • application/json
  • application/xml
  • text/*

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

Note

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.

Coba lagi logika hitungan

Jika mengatur parameter @retry_count , permintaan akan dicoba kembali ketika kesalahan berikut ditemui:

Kesalahan HTTP

Kode Status HTTP Kesalahan Description
408 Batas Waktu Permintaan Klien tidak menghasilkan permintaan dalam batas waktu server atau waktu server habis menunggu.
429 Terlalu Banyak Permintaan Klien sedang dibatasi tarifnya. Coba lagi waktu berdasarkan nilai header "Coba Lagi-Setelah" jika disediakan.
500 Kesalahan Server Internal Kesalahan server generik.
502 Gateway Buruk Server menerima respons yang tidak valid dari backend.
503 Layanan Tidak Tersedia Menunjukkan kelebihan beban atau waktu henti sementara.
504 Batas Waktu Gateway Server tidak mendapatkan respons tepat waktu.

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

Examples

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.

A. Memanggil Fungsi Azure menggunakan pengikatan pemicu HTTP tanpa autentikasi

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

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. 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 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 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. Membaca konten file dari Azure Blob Storage dengan token SAS

Contoh ini membaca file dari Azure Blob Storage menggunakan token SAS untuk autentikasi. Hasilnya dikembalikan dalam XML, jadi Anda harus menggunakan header "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. 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 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 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. 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 dikembalikan dalam XML, jadi Anda harus menggunakan header "Accept":"application/xml".

Mulailah dengan membuat kunci master untuk database Azure SQL. Ganti <password> dengan kata sandi yang kuat.

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

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

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

Selanjutnya, buat file dan tambahkan teks ke dalamnya dengan dua pernyataan berikut. Ganti <domain> dengan jalur yang sesuai.

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

Terakhir, gunakan pernyataan berikut untuk membaca file. Ganti <domain> dengan jalur yang sesuai.

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. Memanggil Azure OpenAI menggunakan Identitas Terkelola

Contoh berikut memanggil model Azure OpenAI menggunakan Identitas terkelola di Microsoft Entra untuk Azure SQL. Ganti <my-azure-openai-endpoint> dan <model-deployment-name> dengan titik akhir Azure OpenAI dan nama model Anda masing-masing, dan pastikan Anda telah memberikan identitas terkelola peran Pengguna OpenAI Cognitive Services di layanan 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

Konten terkait

  • Last updated on