Aracılığıyla paylaş

sp_invoke_external_rest_endpoint (Transact-SQL)

Şunlar için geçerlidir: SQL Server 2025 (17.x) Microsoft Fabric'teAzure SQL VeritabanıAzure SQL Yönetilen Örneği SQL veritabanı

sp_invoke_external_rest_endpoint saklı yordamı, yordama giriş bağımsız değişkeni olarak sağlanan bir HTTPS REST uç noktasını çağırır.

Note

Saklanan prosedür sp_invoke_external_rest_endpoint SQL Server 2025 (17.x) için önizleme aşamasındadır.

Yetkisiz erişim veya veri aktarımı riskini azaltmanın yolları

Caution

sp_invoke_external_rest_endpoint saklı yordamının kullanılması, verilerin bir dış varlığa aktarılmasını sağlar.

Yetkisiz erişim veya veri aktarımı riskini azaltmak için aşağıdaki en iyi güvenlik uygulamalarını göz önünde bulundurun:

  • güçlü erişim denetimleri uygulayın: Yalnızca yetkili kullanıcıların hassas verilere ve REST API uç noktalarına erişimi olduğundan emin olun. en az ayrıcalık ilkesinin yanı sıra veritabanı rollerini ve ayrıcalıklarınıkullanın.
  • Uygun kimlik doğrulaması ve yetkilendirme: Tüm REST çağrılarının kimliğinin doğrulandığından ve yetkisiz erişimi önlemek için yetkilendirildiğinden emin olun.
  • Erişimi izleme ve denetleme: Şüpheli etkinlikleri algılamak için veritabanına ve REST API çağrılarına erişimi düzenli olarak izleyip denetleyebilirsiniz.
  • Düzenli Güvenlik Değerlendirmeleri: Olası riskleri belirlemek ve azaltmak için düzenli güvenlik değerlendirmeleri ve güvenlik açığı taramaları gerçekleştirin.
  • Çalışan eğitimi: Çalışanları veri sızdırma riskleri ve aşağıdaki güvenlik protokollerinin önemi hakkında eğitin.

Syntax

Transact-SQL söz dizimi kuralları

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'

Çağrılacak HTTPS REST uç noktasının URL'si. @url, nvarchar(4000) varsayılan olmayan .

[ @payload = ] N'request_payload'

HTTPS REST uç noktasına gönderilecek yükü içeren JSON, XML veya METNEÇEVİr biçiminde unicode dize. Yüklerin geçerli bir JSON belgesi, iyi biçimlendirilmiş bir XML belgesi veya metin olması gerekir. @payload varsayılan olmayan nvarchar(max) .

[ @headers = ] N'üst bilgileri'

İsteğin bir parçası olarak HTTPS REST uç noktasına gönderilmesi gereken üst bilgiler. Üst bilgiler düz bir JSON (iç içe yapıları olmayan bir JSON belgesi) biçimi kullanılarak belirtilmelidir. Yasak üst bilgi adı listesinde tanımlanan üst bilgiler, @headers parametresinde açıkça geçirilse bile yoksayılır; HTTPS isteği başlatılırken değerleri atılır veya sistem tarafından sağlanan değerlerle değiştirilir.

@headers parametresi, varsayılan olmayan nvarchar(4000) .

[ = ] 'N'yöntemi

URL'yi çağırmak için HTTP yöntemi. Aşağıdaki değerlerden biri olmalıdır: GET, POST, PUT, PATCH, DELETE, HEAD. @method, varsayılan değer olarak olan nvarchar(6) .

[ @timeout = ] saniye

HTTPS çağrısının çalışması için saniye olarak izin verilen süre. Tanımlanan zaman aşımı süresi içinde tam HTTP isteği ve yanıtı saniyeler içinde gönderip alınamıyorsa saklı yordam yürütmesi durdurulmuş olur ve bir özel durum oluşur. Zaman aşımı, HTTP bağlantısı başladığında başlar ve yanıt ve varsa yük dahil edildiğinde biter. @timeout, varsayılan değeri 30 olan pozitif smallint. Kabul edilen değerler: 1 ile 230.

@retry_count parametresi belirtilirse, @timeout parametresi yordam için birikmeli zaman aşımı işlevi görür.

[ @credential = ] kimlik bilgisi

HTTPS isteğine kimlik doğrulama bilgileri eklemek için hangi DATABASE SCOPED CREDENTIAL nesnesinin kullanıldığını belirtin. @credential, sysname varsayılan değer olmadan .

çıktıyı @response

Çağrılan uç noktadan alınan yanıtın belirtilen değişkene geçirilmesine izin verin. @responsenvarchar(max).

[ @retry_count = ] Hatalar varsa yeniden deneme sayısı

Bir hata varsa saklı yordamın belirtilen uç noktaya bağlanmayı kaç kez yeniden denemesi olduğunu belirtir. @retry_count , varsayılan değeri 0 olan pozitif bir küçük resimdir. Kabul edilen değerler: 0 ile 10, 0 tüm yeniden deneme mantığını atlar. Yeniden deneme aralığı, varsa üst bilgi kullanılarak Retry-After belirlenir. Üst bilgi yoksa, sistem belirli hata kodları için üstel geri alma stratejisi uygular. Diğer tüm durumlarda varsayılan olarak 200 milisaniyelik bir gecikme kullanılır.

Dönüş değeri

YÜRÜTME, HTTPS çağrısı yapıldıysa ve alınan HTTP durum kodu bir 2xx durum koduysa (0 ) döndürürSuccess. Alınan HTTP durum kodu 2xx aralığında değilse, döndürülen değer alınan HTTP durum kodudur. HTTPS çağrısı hiç yapılamıyorsa, bir özel durum oluşturulur.

Permissions

Veritabanı izinleri

HERHANGİ Bİr HARİÇ UÇ NOKTA VERITABANı YÜRÜTME izni gerektirir.

Örneğin:

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

SQL Server 2025 ve Azure SQL Yönetilen Örneği'nde etkinleştirme

Note

Saklanan prosedür sp_invoke_external_rest_endpoint SQL Server 2025 (17.x) için önizleme aşamasındadır.

Saklanan prosedür, sp_invoke_external_rest_endpoint SQL Server 2025 (17.x) ve Azure SQL Managed Instance'da SQL Server 2025 veya Always-up-totarihgüncelleme politikası ile mevcuttur ve varsayılan olarak devre dışı bırakılmıştır.

SQL Server 2025 (17.x) ve Azure SQL Managed Instance'da saklanan prosedürü etkinleştirmek sp_invoke_external_rest_endpoint için aşağıdaki T-SQL kodunu çalıştırın:

EXECUTE sp_configure 'external rest endpoint enabled', 1;

RECONFIGURE WITH OVERRIDE;

Bir yapılandırma seçeneğini değiştirmek veya sp_configure deyimini çalıştırmak üzere yürütmek için kullanıcıya ALTER SETTINGS sunucu düzeyinde izin verilmelidir. ALTER SETTINGS izni sysadmin ve serveradmin sabit sunucu rolleri tarafından örtük olarak tutulur.

Note

sp_invoke_external_rest_endpoint , Azure SQL Veritabanı'nda ve Doku'daki SQL veritabanında varsayılan olarak etkindir.

Yanıt biçimi

HTTP çağrısının yanıtı ve çağrılan uç nokta tarafından geri gönderilen sonuç verileri, @response çıkış parametresi aracılığıyla kullanılabilir. @response aşağıdaki şemaya sahip bir JSON belgesi içerebilir:

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

Specifically:

  • yanıt: HTTP sonucunu ve diğer yanıt meta verilerini içeren bir JSON nesnesi.
  • sonuç: HTTP çağrısı tarafından döndürülen JSON yükü. Alınan HTTP sonucu 204 (No Content) ise atlanır.

veya @response aşağıdaki şemaya sahip bir XML belgesi içerebilir:

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

Specifically:

  • yanıt: HTTP sonucunu ve diğer yanıt meta verilerini içeren bir XML nesnesi.
  • sonuç: HTTP çağrısı tarafından döndürülen XML yükü. Alınan HTTP sonucu 204 (No Content) ise atlanır.

response bölümünde, HTTP durum kodu ve açıklaması dışında, alınan yanıt üst bilgileri kümesinin tamamı nesnesinde headers sağlanır. Aşağıdaki örnekte JSON'daki bir response bölümü (metin yanıtlarının yapısı da) gösterilmektedir:

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

Aşağıdaki örnekte XML'de bir response bölümü gösterilmektedir:

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

İzin verilen uç noktalar

Important

Bu liste yalnızca Azure SQL Veritabanı ve Azure SQL Yönetilen Örneği için geçerlidir.

Yalnızca aşağıdaki hizmetler için uç noktalara çağrılara izin verilir:

Azure Hizmeti Domain
Azure Functions *.azurewebsites.net
Azure Apps Hizmeti *.azurewebsites.net
Azure App Service Ortamı *.appserviceenvironment.net
Azure Statik Web Uygulamaları *.azurestaticapps.net
Azure Logic Apps *.logic.azure.com
Azure Event Hubs *.servicebus.windows.net
Azure Event Grid *.eventgrid.azure.net
Azure AI Hizmetleri *.cognitiveservices.azure.com
*.api.cognitive.microsoft.com
Azure OpenAI *.openai.azure.com
PowerApps / Dataverse *.api.crm.dynamics.com
Microsoft Dynamics *.dynamics.com
Azure Konteyner Örnekleri (Azure Container Instances) *.azurecontainer.io
Azure Konteyner Uygulamaları *.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 Depolama *.blob.core.windows.net
Azure Files *.file.core.windows.net
Azure Kuyruk Depolama *.queue.core.windows.net
Azure Tablo Depolama *.table.core.windows.net
Azure İletişim Hizmetleri *.communications.azure.com
Bing Search api.bing.microsoft.com
Azure Key Vault *.vault.azure.net
Azure AI Arama *.search.windows.net
Azure Maps *.atlas.microsoft.com
Azure Yapay Zeka Çevirici api.cognitive.microsofttranslator.com

Dış uç noktalara giden erişimi daha fazla kısıtlamak için Azure SQL Veritabanı ve Azure Synapse Analytics denetim mekanizması için giden güvenlik duvarı kuralları kullanılabilir.

Note

İzin verilenler listesinde olmayan bir REST hizmetini çağırmak istiyorsanız, istenen hizmeti güvenli bir şekilde kullanıma açmak ve sp_invoke_external_rest_endpointiçin kullanılabilir hale getirmek için API Management'ı kullanabilirsiniz.

Limits

Yük boyutu

Hem alındığında hem de gönderildiğinde yük, kablo üzerinden gönderildiğinde UTF-8 kodlanır. Bu biçimde boyutu 100 MB ile sınırlıdır.

URL uzunluğu

En fazla URL uzunluğu (@url parametresi kullanılarak ve varsa sorgu dizesine belirtilen kimlik bilgileri eklendikten sonra oluşturulur) 8 KB'tır; sorgu dizesi uzunluğu üst sınırı (sorgu dizesi + kimlik bilgisi sorgu dizesi) 4 KB'tır.

Üst bilgi boyutu

maksimum istek ve yanıt üst bilgisi boyutu (tüm üst bilgi alanları: @headers parametresi + kimlik bilgisi üst bilgisi + sistem tarafından sağlanan üst bilgiler aracılığıyla geçirilen üst bilgiler) 8 KB'tır.

Throttling

sp_invoke_external_rest_endpoint aracılığıyla dış uç noktalara yapılan eşzamanlı bağlantı sayısı, en fazla 150 çalışanla 10% çalışan iş parçacığına eşlenir. tek bir veritabanında azaltma veritabanı düzeyinde zorlanırken, elastik havuzda azaltma hem veritabanı hem de havuz düzeyinde zorlanır.

Bir veritabanının kaç eşzamanlı bağlantı sürdürebileceğini denetlemek için aşağıdaki sorguyu çalıştırın:

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

Kullanarak dış uç noktaya sp_invoke_external_rest_endpoint yeni bir bağlantı, eşzamanlı bağlantı üst sınırına ulaşıldığında denenirse, hata 10928 (veya elastik havuz sınırlarına ulaştıysanız 10936) oluşur. Örneğin:

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

Bazı REST uç noktalarının düzgün çağrılabilmesi için kimlik doğrulaması gerekir. Kimlik doğrulaması genellikle sorgu dizesinde veya istekle ayarlanan HTTP üst bilgilerinde belirli anahtar-değer çiftleri geçirilerek yapılabilir.

Korumalı uç noktayı çağırmak DATABASE SCOPED CREDENTIAL için kullanılacak sp_invoke_external_rest_endpoint kimlik doğrulama verilerini (örneğin Taşıyıcı belirteci gibi) güvenli bir şekilde depolamak için kullanmak mümkündür. oluştururken DATABASE SCOPED CREDENTIAL, çağrılan uç noktaya hangi kimlik doğrulama verilerinin geçirileceğini ve nasıl yapılacağını belirtmek için parametresini kullanın IDENTITY . IDENTITY dört seçeneği destekler:

  • HTTPEndpointHeaders: İstek Üst Bilgileri kullanarak belirtilen kimlik doğrulama verilerini gönderme
  • HTTPEndpointQueryString: Sorgu Dizesi kullanarak belirtilen kimlik doğrulama verilerini gönderme
  • Managed Identity: İstek üst bilgilerini kullanarak Sistem Tarafından Atanan Yönetilen Kimlik gönderin
  • Shared Access Signature: imzalı URL (SAS olarak da adlandırılır) aracılığıyla kaynaklara sınırlı temsilci erişimi sağlayın

Oluşturulan DATABASE SCOPED CREDENTIAL, @credential parametresi aracılığıyla kullanılabilir:

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

Bu IDENTITY değerle DATABASE SCOPED CREDENTIAL , istek üst bilgilerine eklenir. Kimlik doğrulama bilgilerini içeren anahtar-değer çifti düz bir JSON biçimi kullanılarak parametresi aracılığıyla SECRET sağlanmalıdır. Örneğin:

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

Kimlik bilgisi adı kuralları

Oluşturulan DATABASE SCOPED CREDENTIAL, sp_invoke_external_rest_endpointile kullanılabilmesi için belirli kurallara uymalıdır. Kurallar aşağıdaki gibidir:

  • Geçerli bir URL olmalıdır
  • URL etki alanı, izin verilenler listesine dahil edilen etki alanlarından biri olmalıdır
  • URL bir sorgu dizesi içermemelidir
  • Çağrılan URL'nin Protokol + Tam Etki Alanı Adı (FQDN), kimlik bilgisi adının Protokol + FQDN değeriyle eşleşmelidir
  • Çağrılan URL yolunun her bölümü, kimlik bilgisi adındaki URL yolunun ilgili bölümüyle tamamen eşleşmelidir
  • Kimlik bilgisi, istek URL'sinden daha genel bir yola işaret etmelidir. Örneğin, yol https://northwind.azurewebsite.net/customers için oluşturulan kimlik bilgileri URL https://northwind.azurewebsite.net için kullanılamaz

Harmanlama ve kimlik bilgisi adı kuralları

RFC 3986 Bölüm 6.2.2.1 , "URI genel söz diziminin bileşenlerini kullandığında, bileşen söz dizimi eşdeğerliği kuralları her zaman geçerlidir; diğer bir deyişle, düzen ve konak büyük/küçük harfe duyarlı değildir", RFC 7230 Bölüm 2.7.3 ise "diğer tüm diğerlerinin büyük/küçük harfe duyarlı bir şekilde karşılaştırıldığından" bahseder.

Veritabanı düzeyinde ayarlanmış bir harmanlama kuralı olduğundan, veritabanı harmanlama kuralı ve yukarıda bahsedilen RFC ile uyumlu olması için aşağıdaki mantık uygulanır. (Açıklanan kural, örneğin veritabanı büyük/küçük harfe duyarlı harmanlama kullanacak şekilde ayarlanmışsa RFC kurallarından daha kısıtlayıcı olabilir.):

  1. RFC kullanarak URL ve kimlik bilgilerinin eşleşip eşleşmediğini denetleyin, yani:
    • Büyük/küçük harfe duyarlı olmayan harmanlama (Latin1_General_100_CI_AS_KS_WS_SC) kullanarak düzeni ve konağı denetleyin
    • URL'nin diğer tüm kesimlerinin büyük/küçük harfe duyarlı harmanlamada (Latin1_General_100_BIN2) karşılaştırılmasını denetleyin
  2. Veritabanı harmanlama kurallarını kullanarak (ve URL kodlaması yapmadan) URL'nin ve kimlik bilgilerinin eşleşip eşleşmediğini denetleyin.

Kimlik bilgilerini kullanma izinleri verme

DATABASE SCOPED CREDENTIAL'a erişen veritabanı kullanıcılarının bu kimlik bilgilerini kullanma izni olmalıdır.

Kimlik bilgilerini kullanmak için veritabanı kullanıcısının belirli bir kimlik bilgisi üzerinde REFERENCES izni olmalıdır:

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

Remarks

Bekleme türü

Çağrılan hizmete yapılan çağrının tamamlanmasını beklerken sp_invoke_external_rest_endpoint bir HTTP_EXTERNAL_CONNECTION bekleme türü bildirir.

HTTPS ve TLS

Yalnızca TLS şifreleme protokolü ile HTTPS kullanacak şekilde yapılandırılmış uç noktalar desteklenir.

HTTP yeniden yönlendirmeleri

sp_invoke_external_rest_endpoint çağrılan uç noktadan yanıt olarak alınan HIÇBIR HTTP yeniden yönlendirmesini otomatik olarak izlemez.

HTTP üst bilgileri

sp_invoke_external_rest_endpoint HTTP isteğine otomatik olarak aşağıdaki üst bilgileri ekler:

  • İçerik türü: olarak ayarlayın
  • kabul : olarak ayarlayın
  • kullanıcı aracısı: ayarlayın, örneğin:

Kullanıcı aracısı saklı yordam tarafından her zaman üzerine yazılır, ancak içerik türü ve kabul üst bilgi değerleri @headers parametresi aracılığıyla kullanıcı tarafından tanımlanabilir. İçerik türünde yalnızca medya türü yönergesinin belirtilmesine izin verilir ve karakter kümesi veya sınır yönergelerini belirtmek mümkün değildir.

İstek ve yanıt yükü desteklenen medya türleri

İçerik türüüst bilgi için kabul edilen değerler aşağıdadır.

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

kabul üst bilgisi için kabul edilen değerler aşağıdadır.

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

Metin üst bilgisi türleri hakkında daha fazla bilgi için IANA'daki metin türü kayıt defterine bakın.

Note

REST uç noktasının çağrısını cURL veya Insomniagibi herhangi bir modern REST istemcisiyle test ediyorsanız, aynı davranışa ve sonuçlara sahip olmak için sp_invoke_external_rest_endpoint tarafından otomatik olarak eklenen üst bilgileri eklediğinizden emin olun.

Yeniden deneme sayısı mantığı

@retry_count parametresi ayarlanırsa, aşağıdaki hatalarla karşılaşıldığında istek yeniden denenecek:

HTTP Hataları

HTTP Durum Kodu Hata Description
408 İstek Zaman Aşımı İstemci, sunucunun zaman sınırı içinde bir istek üretmedi veya sunucu beklerken zaman aşımına uğradı.
429 Çok Fazla İstek Var İstemci hız sınırına bağlı. Sağlanan "Yeniden Dene-Sonra" üst bilgi değerine göre zamanı yeniden deneyin.
beş yüz İç Sunucu Hatası Genel sunucu hatası.
502 Hatalı Ağ Geçidi Sunucu arka uçtan geçersiz bir yanıt aldı.
503 Hizmet Kullanılamıyor Geçici bir aşırı yükleme veya kapalı kalma süresini gösterir.
504 Ağ Geçidi Zaman Aşımı Sunucu zamanında yanıt alamadı.

En iyi yöntemler

Toplu işlem tekniği kullanma

Rest uç noktasına, örneğin azure işlevine veya olay hub'ına bir satır kümesi göndermeniz gerekiyorsa, gönderilen her satır için HTTPS çağrısı ek yükünü önlemek için satırları tek bir JSON belgesine toplu olarak göndermeniz önerilir. Bu, FOR JSON deyimi kullanılarak yapılabilir, örneğin:

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

Burada sp_invoke_external_rest_endpoint kullanarak Azure İşlevleri veya Azure Event Hubs gibi yaygın Azure Hizmetleri ile tümleştirme hakkında bazı örnekler bulabilirsiniz. GitHubdiğer hizmetlerle tümleştirmeye yönelik daha fazla örnek bulunabilir.

A. Kimlik doğrulaması olmadan HTTP tetikleyici bağlaması kullanarak Azure İşlevi çağırma

Aşağıdaki örnek, anonim erişime izin veren bir HTTP tetikleyici bağlaması kullanarak bir Azure İşlevini çağırır.

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. Yetkilendirme anahtarıyla HTTP tetikleyici bağlaması kullanarak Azure İşlevi çağırma

Aşağıdaki örnek, yetkilendirme anahtarı gerektirecek şekilde yapılandırılmış bir HTTP tetikleyici bağlaması kullanarak azure işlevini çağırır. Yetkilendirme anahtarı, Azure İşlevleri'nin x-function-key gerektirdiği şekilde üst bilgide geçirilir. Daha fazla bilgi için bkz. Azure İşlevleri - API anahtarı yetkilendirme.

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. SAS belirteci ile Azure Blob Depolama'dan bir dosyanın içeriğini okuma

Bu örnek, kimlik doğrulaması için SAS belirteci kullanarak Azure Blob Depolama'dan bir dosya okur. Sonuçlar XML olarak döndürülür, bu nedenle üst bilgisini "Accept":"application/xml"kullanmanız gerekir.

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. Azure SQL Veritabanı Yönetilen Kimliği'ni kullanarak olay hub'ına ileti gönderme

Bu örnek, Azure SQL Yönetilen Kimliği'ni kullanarak Event Hubs'a nasıl ileti gönderebileceğinizi gösterir. Veritabanınızı barındıran Azure SQL Veritabanı mantıksal sunucusu için sistem tarafından yönetilen kimlik yapılandırdığınızdan emin olun, örneğin:

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

Bundan sonra Event Hubs'ı Azure SQL Server'ın Yönetilen Kimliği'nin istenen olay hub'ına ileti gönderebilmesine ("Azure Event Hubs Veri Göndereni" rolü) izin verecek şekilde yapılandırın. Daha fazla bilgi için bkz. Event Hubs'ı yönetilen kimliklerle kullanma.

Bu işlem tamamlandıktan sonra tarafından Managed Identitykullanılan veritabanı kapsamlı kimlik bilgilerini tanımlarken kimlik adını kullanabilirsinizsp_invoke_external_rest_endpoint. 'de açıklandığı gibiEvent Hubs kaynaklarına erişmek için Microsoft Entra Kimliği ile bir uygulamanın kimliğini doğrulama, Microsoft Entra kimlik doğrulaması kullanılırken kullanılacak kaynak adı (veya kimliği) 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. Azure SQL Veritabanı kapsamlı kimlik bilgileriyle Azure Dosya Depolama'ya dosya okuma ve yazma

Bu örnek, kimlik doğrulaması için Azure SQL Veritabanı kapsamlı kimlik bilgilerini kullanarak bir Azure Dosya Depolama'ya dosya yazar ve ardından içeriği döndürür. Sonuçlar XML olarak döndürülür, bu nedenle üst bilgisini "Accept":"application/xml"kullanmanız gerekir.

Azure SQL veritabanı için bir ana anahtar oluşturarak başlayın. değerini güçlü bir parolayla değiştirin <password> .

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

Ardından, Azure Blob Depolama Hesabı tarafından sağlanan SAS belirtecini kullanarak veritabanı kapsamlı kimlik bilgilerini oluşturun. değerini sağlanan SAS belirteci ile değiştirin <token> .

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

Ardından, aşağıdaki iki deyimle dosyayı oluşturun ve dosyaya metin ekleyin. değerini uygun yol ile değiştirin <domain> .

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

Son olarak, dosyayı okumak için aşağıdaki deyimi kullanın. değerini uygun yol ile değiştirin <domain> .

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. Yönetilen Kimlik kullanarak Azure OpenAI çağırma

Aşağıdaki örnek, Azure SQL için Microsoft Entra'da Yönetilen kimlikleri kullanan bir Azure OpenAI modelini çağırır. ve değerini sırasıyla Azure OpenAI uç noktanız ve model adınızla değiştirin <my-azure-openai-endpoint> ve Yönetilen Kimliğe Azure <model-deployment-name> rolü verdiğinizden emin olun.

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

İlgili içerik

  • Last updated on