Bir App Service uygulamasını Foundry Aracısı Hizmeti'nde (Spring Boot) araç olarak ekleme

Bu öğreticide, OpenAPI aracılığıyla Spring Boot web uygulamasının işlevselliğini kullanıma sunmayı, bunu Foundry Agent Service'e araç olarak eklemeyi ve aracıların oyun alanında doğal dil kullanarak uygulamanızla etkileşim kurmayı öğreneceksiniz.

Web uygulamanızın zaten alışveriş, otel rezervasyonu veya veri yönetimi gibi kullanışlı özellikleri varsa, bu özellikleri Foundry Agent Service'teki bir yapay zeka temsilcisinin kullanımına açmak kolaydır. Yalnızca uygulamanıza bir OpenAPI şeması ekleyerek, aracının kullanıcı istemlerine yanıt verirken uygulamanızın özelliklerini anlamasını ve kullanmasını sağlarsınız. Uygulamanızın yapabileceği her şeyi yapay zeka aracınız da yapabilir; tek gereken, uygulamanız için bir OpenAPI uç noktası oluşturmaktır. Bu öğreticide basit bir to-do listesi uygulamasıyla başlayacaksınız. Sonunda, konuşma yapay zekası aracılığıyla bir aracıyla görev oluşturabilecek, güncelleştirebilecek ve yönetebileceksiniz.

OpenAPI aracını kullanarak eylemde bulunan bir konuşmanın ortasında aracıların oyun alanının gösterildiği ekran görüntüsü.

Web uygulamanıza OpenAPI işlevselliği ekleyin.
OpenAPI şemasının Foundry Agent Service ile uyumlu olduğundan emin olun.
Uygulamanızı Foundry Agent Service'e OpenAPI aracı olarak kaydedin.
Temsilcinizi aracı oyun alanında test edin.

Önkoşullar

Bu öğretici, Tutorial: Linux ve Azure Cosmos DB üzerinde Azure App Service ile Java Spring Boot web uygulaması derleme bölümünde kullanılan örnekle çalıştığınızı varsayar.

En azından GitHub Codespaces'ta örnek uygulamayı açın ve komutunu çalıştırarak azd upuygulamayı dağıtın.

Web uygulamanıza OpenAPI işlevselliği ekleme

Tavsiye

Aracı modunda GitHub Copilot'a haber vererek aşağıdaki tüm değişiklikleri yapabilirsiniz:

I'd like to generate OpenAPI functionality using Spring Boot OpenAPI. Please also generate the server URL and operation ID in the schema.

kod alanında pom.xml açın ve aşağıdaki bağımlılığı ekleyin:

<dependency>
    <groupId>org.springdoc</groupId>
    <artifactId>springdoc-openapi-starter-webmvc-ui</artifactId>
    <version>2.6.0</version>
</dependency>

src/main/java/com/microsoft/azure/appservice/examples/springbootmongodb/controller/TodoListController.java açın ve aşağıdaki içeri aktarmaları ekleyin.
```
import io.swagger.v3.oas.annotations.Operation;
import io.swagger.v3.oas.annotations.tags.Tag;
```
TodoListController sınıfı uygular@RestController, bu nedenle OpenAPI ile uyumlu olması için yalnızca birkaç ek açıklama eklemeniz gerekir. Ayrıca, API'leri Döküm Aracı Hizmeti ile uyumlu hale getirmek için ek açıklama içinde operationId özelliğini belirtmeniz @Operation gerekir (bkz. OpenAPI Belirtilen Araçlarla Döküm Aracı Hizmeti'ni kullanma: Önkoşullar).

Sınıf bildirimini bulun ve aşağıdaki kod parçacığında gösterildiği gibi ek açıklamayı ekleyin @Tag :

@RestController
@Tag(name = "Todo List", description = "Todo List management APIs")
public class TodoListController {

Yöntem bildirimi getTodoItem bulun ve @Operation açıklamasını description ve operationId ile ekleyin, aşağıdaki kod parçacığında gösterildiği gibi:

@Operation(description = "Returns a single todo item", operationId = "getTodoItem")
@GetMapping(path = "/api/todolist/{index}", produces = {MediaType.APPLICATION_JSON_VALUE})
public TodoItem getTodoItem(@PathVariable("index") String index) {

Yöntem bildirimi getAllTodoItems bulun ve @Operation açıklamasını description ve operationId ile ekleyin, aşağıdaki kod parçacığında gösterildiği gibi:

@Operation(description = "Returns a list of all todo items", operationId = "getAllTodoItems")
@GetMapping(path = "/api/todolist", produces = {MediaType.APPLICATION_JSON_VALUE})
public List<TodoItem> getAllTodoItems() {

Yöntem bildirimi addNewTodoItem bulun ve @Operation açıklamasını description ve operationId ile ekleyin, aşağıdaki kod parçacığında gösterildiği gibi:

@Operation(description = "Creates a new todo item", operationId = "addNewTodoItem")
@PostMapping(path = "/api/todolist", consumes = MediaType.APPLICATION_JSON_VALUE)
public String addNewTodoItem(@RequestBody TodoItem item) {

Yöntem bildirimi updateTodoItem bulun ve @Operation açıklamasını description ve operationId ile ekleyin, aşağıdaki kod parçacığında gösterildiği gibi:

@Operation(description = "Updates an existing todo item", operationId = "updateTodoItem")
@PutMapping(path = "/api/todolist", consumes = MediaType.APPLICATION_JSON_VALUE)
public String updateTodoItem(@RequestBody TodoItem item) {

Yöntem bildirimi deleteTodoItem bulun ve @Operation açıklamasını description ve operationId ile ekleyin, aşağıdaki kod parçacığında gösterildiği gibi:
```
@Operation(description = "Deletes a todo item by ID", operationId = "deleteTodoItem")
@DeleteMapping("/api/todolist/{id}")
public String deleteTodoItem(@PathVariable("id") String id) {
```
Bu minimum yapılandırma, springdoc-openapi'de belgelendiği gibi aşağıdaki ayarları sağlar:
- Swagger kullanıcı arabirimi /swagger-ui.html konumunda.
- OpenAPI spesifikasyonu /v3/api-docs konumunda.
Codespace terminalinde, uygulamayı mvn spring-boot:run ile çalıştırın.
Tarayıcıda Aç'ı seçin.
URL'ye ekleyerek /swagger-ui.html Swagger kullanıcı arabirimine gidin.
API işlemlerini Swagger kullanıcı arabiriminde deneyerek çalıştığını onaylayın.
Kod alanı terminaline geri dönerek, değişikliklerinizi işleyerek (GitHub Actions yöntemi) veya azd up komutunu çalıştırarak (Azure Geliştirici CLI yöntemi) değişikliklerinizi dağıtın.
Değişiklikleriniz dağıtıldıktan sonra adresine gidin https://<your-app's-url>/v3/api-docs ve daha sonra kullanmak üzere şemayı kopyalayın.

Microsoft Foundry'de aracı oluşturma

Uyarı

Bu adımlarda yeni Foundry portalı kullanılır.

Dökümhane portalının sağ üst menüsünde Yeni Dökümhane'yi seçin.
Yeni Dökümhane portalında ilk kez geliyorsanız proje adını seçin ve Yeni proje oluştur'u seçin.
Projenize bir ad verin ve Oluştur'u seçin.
Oluşturmaya başla'yı ve ardından Aracı oluştur'u seçin.
Aracınıza bir ad verin ve Oluştur'u seçin. Aracı hazır olduğunda, temsilci oyun alanı görmelisiniz.

Kullanabileceğiniz modelleri ve kullanılabilir bölgeleri not edin.
Aracı oyun alanında Araçlar'ı genişletin ve Ekle>Özel>OpenAPI aracı>Oluştur'u seçin.
Araci bir ad ve bir açiklama verin. OpenAPI 3.0+ şema kutusuna, daha önce kopyaladığınız şemayı yapıştırın.
Araç oluştur'u seçin.
Kaydetseçeneğini seçin.

Tavsiye

Bu öğreticide, OpenAPI aracı kimlik doğrulaması olmadan uygulamanızı anonim olarak çağıracak şekilde yapılandırılır. Üretim senaryolarında, aracı yönetilen kimlik doğrulaması ile güvence altına almalısınız. Adım adım yönergeler için bkz. Foundry Agent Service için OpenAPI uç noktalarının güvenliğini sağlama.

Aracıyı test edin

Yönergeler'de, "Görevleri yönetmeye yardımcı olması için lütfen todosApp aracını kullanın" gibi bazı basit yönergeler verin.
Aşağıdaki istem önerileriyle temsilciyle sohbet edin.
- Bana tüm görevleri göster.
- "Üç marul şakası yapın" adlı bir görev oluşturun.
- Bunu "Üç nakavt şakasıyla gel" olarak değiştirin.

En iyi güvenlik uygulamaları

Azure App Service'te OpenAPI aracılığıyla API'leri gösterirken şu en iyi güvenlik yöntemlerini izleyin:

Kimlik Doğrulaması ve Yetkilendirme: Microsoft Entra kimlik doğrulaması ile OpenAPI uç noktalarınızı koruyun. Adım adım yönergeler için bkz. Foundry Agent Service için OpenAPI uç noktalarının güvenliğini sağlama. Ayrıca Microsoft Entra Id ile Azure API Management'ın arkasındaki uç noktalarınızı koruyabilir ve araçlara yalnızca yetkili kullanıcıların veya aracıların erişebildiğinden emin olabilirsiniz.
Giriş verilerini doğrulama ve temizleme: Bu öğreticideki örnek kod, basitlik ve netlik için giriş doğrulama ve temizlemeyi atlar. Üretim senaryolarında, uygulamanızı korumak için her zaman doğru doğrulama ve temizleme uygulayın. Spring için bkz . Spring: Form Girişi Doğrulanıyor.
HTTPS kullanın: Örnek, varsayılan olarak HTTPS'yi zorlayan ve aktarımdaki verileri şifrelemek için ücretsiz TLS/SSL sertifikaları sağlayan Azure App Service'e dayanır.
CORS'leri sınırla: Çıkış Noktaları Arası Kaynak Paylaşımı'nı (CORS) yalnızca güvenilen etki alanlarıyla kısıtlayın. Daha fazla bilgi için bkz. CORS'yi etkinleştirme.
Hız sınırlama uygula: Kötüye kullanım ve hizmet reddi saldırılarını önlemek için API Management veya özel ara yazılım kullanın.
Hassas uç noktaları gizle: OpenAPI şemanızda iç veya yönetici API'lerini açığa çıkarmaktan kaçının.
OpenAPI şemasını gözden geçirin: OpenAPI şemanızın hassas bilgileri (iç URL'ler, gizli diziler veya uygulama ayrıntıları gibi) sızdırmadığından emin olun.
Bağımlılıkları güncel tutun: NuGet paketlerini düzenli olarak güncelleştirin ve güvenlik önerilerini izleyin.
Etkinliği izle ve kaydet: Şüpheli etkinliği tespit etmek için erişim ve günlük takibini etkinleştirin.
Yönetilen kimlikleri kullanma: Diğer Azure hizmetlerini çağırırken, sabit kodlanmış kimlik bilgileri yerine yönetilen kimlikleri kullanın.

Daha fazla bilgi için bkz . App Service uygulamanızın güvenliğini sağlama ve REST API güvenliği için en iyi yöntemler.

Sonraki adım

Artık App Service uygulamanızın Foundry Agent Service tarafından bir araç olarak kullanılmasını etkinleştirdiniz ve aracıların oyun alanında doğal dil aracılığıyla uygulamanızın API'leriyle etkileşime geçtiniz. Buradan, Foundry portalında aracınıza özellik eklemeye devam edebilir, Microsoft Foundry SDK'sını veya REST API'sini kullanarak kendi uygulamalarınızla tümleştirebilir veya daha büyük bir çözümün parçası olarak dağıtabilirsiniz. Microsoft Foundry'de oluşturulan aracılar bulutta çalıştırılabilir, sohbet botlarıyla tümleştirilebilir veya web ve mobil uygulamalara eklenebilir.

Uyarı

Foundry Agent Service'in şu anda bir Java SDK'sı yoktur. Oluşturduğunuz aracıyı nasıl kullanabileceğinizi görmek için, Öğretici: Microsoft Semantic Kernel veya Foundry Agent Service (.NET) ile Azure App Service'te aracı bir web uygulaması derleme başlığına bakın.

Daha fazla kaynak

Geri Bildirim

Bu sayfayı yararlı buldunuz mu?

Last updated on 2025-12-16