Bir App Service uygulamasını Foundry Agent Service'te araç olarak ekleme (Node.js)

Bu öğreticide, OpenAPI aracılığıyla bir Express.js 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.

Prerequisites

Bu öğreticide , Öğretici: Azure'a Node.js + MongoDB web uygulaması dağıtma bölümünde kullanılan örnekle çalıştığınız varsayılır.

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

Kod alanı terminalinde Projenize NuGet swagger-jsdoc NPM paketini ekleyin:
```
npm install swagger-jsdoc
```

Yolları/index.jsaçın. Dosyanın en altına aşağıdaki module.exports = router; API işlevlerini ekleyin. Bunları Döküm Aracı Hizmeti ile uyumlu hale getirmek için ek açıklama içinde operationId özelliğini belirtmeniz @swagger gerekir (bkz. OpenAPI Belirtilen Araçlarla Döküm Aracı Hizmeti'ni kullanma: Önkoşullar).

router.get('/schema', function(req, res, next) {
  try {
    const swaggerJsdoc = require('swagger-jsdoc');

    res.json(
      swaggerJsdoc(
        {
          definition: {
            openapi: '3.0.0',
            servers: [
              {
                url: `${req.protocol}://${req.get('host')}`,
                description: 'Task API',
              },
            ],
          },
          apis: ['./routes/*.js'],
        }
      )
    );
  } catch (error) {
    res.status(500).json({ error: error.message });
  }
});

/**
 * @swagger
 * /api/tasks:
 *   get:
 *     summary: Get all tasks
 *     operationId: getAllTasks
 *     responses:
 *       200:
 *         description: List of tasks
 */
router.get('/api/tasks', async function(req, res, next) {
  try {
    const tasks = await Task.find();
    res.json(tasks);
  } catch (error) {
    res.status(500).json({ error: error.message });
  }
});

/**
 * @swagger
 * /api/tasks/{id}:
 *   get:
 *     summary: Get task by ID
 *     operationId: getTaskById
 *     parameters:
 *       - in: path
 *         name: id
 *         required: true
 *         schema:
 *           type: string
 *     responses:
 *       200:
 *         description: Task details
 */
router.get('/api/tasks/:id', async function(req, res, next) {
  try {
    const task = await Task.findById(req.params.id);
    res.json(task);
  } catch (error) {
    res.status(404).json({ error: error.message });
  }
});

/**
 * @swagger
 * /api/tasks:
 *   post:
 *     summary: Create a new task
 *     operationId: createTask
 *     requestBody:
 *       required: true
 *       content:
 *         application/json:
 *           schema:
 *             type: object
 *             properties:
 *               taskName:
 *                 type: string
 *     responses:
 *       201:
 *         description: Task created
 */
router.post('/api/tasks', async function(req, res, next) {
  try {
    // Set createDate to current timestamp when creating a task
    const taskData = {
      ...req.body,
      createDate: new Date()
    };

    const task = new Task(taskData);
    await task.save();
    res.status(201).json(task);
  } catch (error) {
    res.status(400).json({ error: error.message });
  }
});

/**
 * @swagger
 * /api/tasks/{id}:
 *   put:
 *     summary: Update a task
 *     operationId: updateTask
 *     parameters:
 *       - in: path
 *         name: id
 *         required: true
 *         schema:
 *           type: string
 *     requestBody:
 *       required: true
 *       content:
 *         application/json:
 *           schema:
 *             type: object
 *             properties:
 *               taskName:
 *                 type: string
 *               completed:
 *                 type: boolean
 *     responses:
 *       200:
 *         description: Task updated
 */
router.put('/api/tasks/:id', async function(req, res, next) {
  try {
    // If completed is being set to true, also set completedDate
    if (req.body.completed === true) {
      req.body.completedDate = new Date();
    }

    const task = await Task.findByIdAndUpdate(req.params.id, req.body, { new: true });
    res.json(task);
  } catch (error) {
    res.status(400).json({ error: error.message });
  }
});

/**
 * @swagger
 * /api/tasks/{id}:
 *   delete:
 *     summary: Delete a task
 *     operationId: deleteTask
 *     parameters:
 *       - in: path
 *         name: id
 *         required: true
 *         schema:
 *           type: string
 *     responses:
 *       200:
 *         description: Task deleted
 */
router.delete('/api/tasks/:id', async function(req, res, next) {
  try {
    const task = await Task.findByIdAndDelete(req.params.id);
    res.json({ message: 'Task deleted successfully', task });
  } catch (error) {
    res.status(404).json({ error: error.message });
  }
});

Bu kod, var olan yolların işlevselliğini çoğaltıyor ve bu gereksizdir, ancak kolaylık sağlamak için bu özelliği kullanacaksınız. En iyi yöntem, uygulama mantığını paylaşılan işlevlere taşımak, ardından bunları hem MVC yollarından hem de OpenAPI yollarından çağırmaktır.

Codespace terminalinde, uygulamayı npm start ile çalıştırın.
Tarayıcıda Aç'ı seçin.
URL'ye ekleyerek /schema OpenAPI şemasını görüntüleyin.
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>/schema 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ıyla güvence altına almayı sağlamalı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: Geçersiz veya kötü amaçlı girişi önlemek için her zaman gelen verileri doğrulayın. Node.js uygulamaları için veri doğrulama kurallarını zorunlu kılmak için express-validator gibi kitaplıkları kullanın. En iyi yöntemler ve uygulama ayrıntıları için belgelerine bakın.
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.

Bir sonraki adıma geçmek ve aracınızı doğrudan Azure App Service'te çalıştırmayı öğrenmek için aşağıdaki öğreticiye bakın:

Öğretici: Microsoft Semantic Kernel veya Foundry Agent Service (.NET) ile Azure App Service'te aracı web uygulaması oluşturma

Daha fazla kaynak

Geri Bildirim

Bu sayfayı yararlı buldunuz mu?

Last updated on 2025-12-16