Aracınızı REST API'den araçlarla genişletme (önizleme)

Note

Bu makale, standard harness ile desteklenen ajanlarda veya ajan akışlarında kullanılan özellikleri açıklamaktadır.

[Bu makale yayın öncesi belgedir ve değişebilir.]

Oluşturduğunuz bir ajanı harici sistemlerle bağlamak ve ajanınızda kullanılmak üzere mevcut verilere erişmek için REST API'lerini (OpenAI API dahil) kullanın. Copilot Studio'ya üç şey sağlayarak temsilcinizi REST API'sine bağlayın:

• API'nin işlevlerini ve kullanılabilir eylemlerini tanımlayan bir OpenAPI belirtimi
• Gerekli kimlik doğrulama türü ve kullanıcıların harici sisteme erişmek için API'ye bağlanması için kimlik doğrulama bilgileri
• Dil modelinin verileri kullanmak için API'yi ne zaman çağıracağını belirlemesine yardımcı olan açıklamalar

Copilot Studio üzerinden Copilot ajanlarına ve özel ajanlara REST API'leri ekleyin.

Important

Bu makale Microsoft Copilot Studio önizleme belgelerini içerir ve değiştirilebilir.

Önizleme özellikleri, üretimde kullanıma yönelik değildir ve sınırlı işlevselliğe sahip olabilir. Bu özellikler, önceden erişebilmeniz ve geri bildirim sağlamanız amacıyla resmi sürümden önce kullanıma sunulur.

Üretime hazır bir aracı oluşturuyorsanız bkz. Microsoft Copilot Studio Overview.

Copilot aracıları, oluşturucuların bağlayıcılar, API'ler, istemler ve bilgi kaynakları gibi birden çok veri kaynağını tek bir aracıda birleştirmesine olanak sağlar. Microsoft 365 Copilot gibi Microsoft markalı aracı deneyimlerini genişletmek için bu aracıyı kullanın.

Özel aracılar bağlayıcılar, API'ler, istemler ve bilgi kaynakları içeren tek başına aracılardır. Özel aracıları doğrudan web sitelerine veya diğer kanallara entegre ederek kullanabilirsiniz.

Note

OpenAPI v2 belirtiminden REST API araçları oluşturmanız gerekir. Bu gereksinim, Power Platform'un API belirtimlerini işleme davranışından kaynaklanır. Bir v3 belirtimi gönderirseniz, oluşturma işlemi bunu otomatik olarak bir v2 belirtimine çevirir.

Prerequisites

• Üretici düzeyi kimlik bilgileri ve Copilot Studio lisansı.
• Bağlanmak istediğiniz REST API için OpenAPI spesifikasyonunun bir kopyası
• API'ye bağlanmak için gereken kimlik doğrulama türü ve kimlik doğrulama detayları hakkında bilgi.

Ajanınıza bir REST API aracı ekleyin

Aracınıza REST API aracı eklemek için aşağıdaki adımları tamamlayın:

1. Yeni bir ajan aracı ekleyin ve REST API'yi seçin
2. API spesifikasyonu, açıklaması ve çözümü sağla
3. Kimlik doğrulama detaylarını sağla
4. API'den seçilmiş araçlar
5. İnceleme ve yayımlama

Aşağıdaki bölümler süreci adım adım size rehberlik eder.

REST API ekleme işlemi hem özel aracılar hem de Microsoft 365 Copilot aracıları için aynıdır.

Yeni ajan aracı ekle ve REST API'sini seç

1. Temsilcinizin Genel Bakış sayfasına gidin.

2. Araçlar bölümünde Araç ekle'yi seçin. Araçlar sekmesine gidip Araç ekle'yi de seçebilirsiniz.

   Ekle araç sayfası görünüyor.

3. Yeni araç>REST API'sini seçin.

API spesifikasyonu, açıklaması ve çözümü sağla

1. Bağlanmak istediğiniz REST API için bir OpenAPI belirtim dosyası yükleyin. Spesifikasyon dosyasını REST API yüklen ekranına sürükleyip bırakabilir veya kullanmak istediğiniz dosyayı bulmak için sisteminizi gezdirebilirsiniz.

   

   Note

   OpenAPI belirtimi, v2 biçiminde bir JSON dosyası olmalıdır. Bir v3 belirtimi gönderirseniz, oluşturma işlemi bunu otomatik olarak bir v2 belirtimine çevirir.

   Spesifikasyonu yükledikten sonra ekran, spesifikasyon dosya adını ve ayrıntılarını gösterecek şekilde güncellenir.

   

   Aşağıdaki adımlarda yordam, bir ADO bilet yönetim sistemi olan SunnyADO'nun belirli bir örneğini kullanır. Örnekte, amaç kullanıcıların biletlerini ajandan alıp güncellemesine izin vermektir.

2. Ayrıntıları doğrulayın ve İleri'yi seçin.

   API hakkında daha fazla bilgi verebileceğiniz bir API eklentisi detayları sayfası sunulur.

   

   Açıklama alanı başlangıçta karşıya yüklediğiniz API belirtimindeki açıklamaya göre doldurulur. Aracı düzenlemesi belirli bir aracın ne zaman kullanılacağını belirlemek için açıklamayı kullandığından ayrıntılı bir açıklama sağlayın. Ajanınızın seçim sürecinde yardımcı olması için eş anlamlılar da dâhil olmak üzere ayrıntılar sağlayın.

   Örneğin, sağlanan ilk açıklama şöyledir: "Biletleri yönetmek için basit bir hizmet."

   Daha iyi bir tanım şudur: "SunnyADO'dan mevcut biletleri almak, bulmak ve görüntülemek için kullanılan bir sistem." Kayıtları iyileştirmek için daha fazla veri sağlamak için kullanıcıların biletleri güncellemesine, değiştirmesine ve yönetmesine olanak tanır.

3. Açıklama alanına geliştirilmiş bir açıklama girin.

4. Çözüm altındaki bir açılan liste, geçerli ortamdaki kullanılabilir tüm çözümleri listeler. Kullanmak istediğiniz çözümü seçin. Çözüm kavramları bölümünde çözümler hakkında daha fazla bilgi edinin.

   Tercih ettiğiniz bir çözümünüz varsa veya seçili bağlayıcınız zaten çözümdeyse bu çözüm otomatik olarak seçilir.

   Bir çözüm seçebilir veya boş bırakabilirsiniz. Çözümü boş bırakırsanız, sistem sizin için eylem adı ve varsayılan yayıncıyla bir çözüm oluşturur. Eyleminizi bir çözümde depolamak, eyleminizi kolay bir şekilde ortamlar arasında taşımanıza olanak sağlar.

   Note

   Bu durumda varsayılan çözümü veya varsayılan çözümü seçenek olarak görmüyorsanız, kolay yönetim için özel bir çözüm ekleyin. Daha fazla bilgi için bkz. Varsayılan çözüm ve özel çözüm.

5. Bir çözüm seçiliyken, devam etmek için İleri'yi seçin.

Kimlik doğrulama detaylarını sağla

Kimlik Doğrulama sayfası görüntülenir. API için kullanılacak kimlik doğrulaması türünü seçin.

1. Listeden bir kimlik doğrulama yöntemi seçin. Üç seçenek vardır:

   • Yok: API'ye erişmek için kimlik doğrulaması gerekmez.
   • API anahtarı: API'niz kimlik doğrulama için API anahtarı gerektiriyorsa bu seçeneği seçin. Çalışma zamanında, ajan API aracını kullanmak istediğinde, ajan kullanıcıya kimlik doğrulaması için uyarır. Kullanıcı bir API anahtarı sağlar ve ajan bu anahtarla API'ye bağlanır.
   • Doğrulama 2.0: MCP sunucunuz kimlik doğrulama için OAuth 2.0 kullanıyorsa bu seçeneği seçin. OAuth 2.0, bireysel kullanıcıların bir kimlik sağlayıcısı aracılığıyla API'ye kimlik doğrulama yapmasına olanak tanır. Bu kimlik doğrulama yöntemi, kullanıcının kimlik bilgilerini aracıyla paylaşmadan uygulamanıza (aracı) izin vermesine olanak tanır.

2. Seçilen kimlik doğrulama yöntemi için gerekli alanları girin. Alanlar, kimlik doğrulama yöntemine göre değişir.

   • Hiç: Verilecek bilgi yok.
   • API Anahtarı:
     • Parametre etiketi: API parametresinin kullanıcılara sunulması için metin etiketi.
     • Parametre adı: ÜST bilgi veya sorgu dizesinde kullanılacak API anahtarı parametresinin gerçek adı.
     • Parametre konumu: API için anahtarı gönderme. Başlık veya Sorgu seçeneğini seçin.
   • Kimlik Doğrulaması 2.0:
     • İstemci Kimliği: Uygulamanızı kaydederken kimlik sağlayıcısının verdiği istemci tanımlayıcısı. İstemci kimliği, kimlik sağlayıcısının isteği hangi uygulamanın yaptığını bilmesini sağlar.
     • istemci gizli anahtarı: Uygulamanızı kaydettiğinizde kimlik sağlayıcısının verdiği istemci gizli anahtarı. Aracınız, MCP sunucusu için erişim belirteçleri talep etmek üzere yetkili olduğunu kanıtlamak amacıyla istemci kimliği ile birlikte istemci gizliliğini gönderir.
     • Yetkilendirme URL'si: Aracınızın kullanıcıyı oturum açmak ve aracınıza izin vermek için yönlendirdiği kimlik sağlayıcısı uç noktası (aracı sohbetinde sunulan onay kartı). Kullanıcı burada kimlik doğrulaması yapar ve kimlik sağlayıcısı bir yetkilendirme koduylageri çağırma URL'sinde aracıya geri yanıt verir.
     • Token URL: Ajanınızın yetkilendirme kodunu (veya yenileme belirtekenini) erişim belirtekeni ve yenileme belirtekeni ile değiştirerek aldığı uç nokta. Erişim belirteci, aracınızın kullanıcı adına MCP sunucusunu kullanmasına olanak tanır. Yenileme belirteçleri, önceki erişim belirtecinin süresi dolduğunda aracınızın yenileme uç noktasından yeni erişim ve yenileme belirteçleri almasına olanak sağlar.
     • Yenileme URL'si: Yenileme belirteci kullanarak yeni erişim belirteci istemek için uç noktadır (böylece belirtecin süresi dolduğunda kullanıcının yeniden oturum açması gerekmez).
     • Kapsam: (İsteğe bağlı): Uygulamanızın istediği izinler, boşluklara ayrılmış bir liste olarak.
     • Hangi Microsoft 365 kuruluşu uç noktalara erişiyor: Bu ayar, kaynağa erişimi ya oluşturucunun kuruluşuyla ya da tüm kuruluşlarla sınırlar. Aşağıdakilerden birini seçin:
       • Sadece benim organizasyonum
       • Microsoft 365 kuruluşları
     • Hangi uygulamanın (istemcin) uç noktaları kullanabileceği: GUID, bu verilere erişilebilecek istemci sistemini tanımlar. Uygulamalar Microsoft 365, Power Automate ve diğer seçenekleri içerebilir.

3. Tüm alanları tamamladığınızda İleri'yi seçin.

   Aracınızı seçin ve yapılandırın sayfası, API'den etkinleştirebileceğiniz araçları seçebileceğiniz yerdir.

   

API'den seçilmiş araçlar

REST API'den API destekli araçları seçerek ajanınıza ekleyin. Genel olarak, bir REST API, API spesifikasyonunda tanımlanan uç nokta ve HTTP yöntemlerinin (get, put, post, delete vb.) kombinasyonları aracılığıyla çeşitli araçlar sunar. Bazı durumlarda, aracının kullanıcılarının API'nin genel olarak sunduğu her eylemi yürütme yetkisine sahip olmasını istemeyebilirsiniz. Örneğin, API spesifikasyonunuz güncelleme ve silme yeteneğini içerebilir ancak sadece ajanınızın kullanıcılarının kayıt oluşturabilmesini istersiniz.

1. Yapılandırmak için listeden bir araç seçin.

   Aracınızı yapılandırma sayfası görüntülenir.

   

2. Seçilen aracın adını ve açıklamasını belirleyin. Genel API'ye benzer şekilde bir Araç adı ve Araç açıklaması sağlayın. Açıklamalar başlangıçta API spesifikasyonundaki açıklamalardan alınarak doldurulur. Adın benzersiz olması gerekmez, ancak aracın kendisini temsil etmesi gerekir. Açıklama, genel API açıklaması gibi, dil modeline sorgunuzun bu özel araçla uyum yapıp olmadığını daha iyi belirlemek için detaylar sağlayacak kadar spesifik olmalıdır.

3. Alanlar tamamlandıktan sonra İleri'yi seçin.

   Aracınızın Parametrelerini Gözden Geçir sayfası görüntülenir.

   

   Bu sayfa, girdi için beklenen değerleri ve döndürülen çıktı değerlerini gösterir. Bu değerleri değiştiremezsiniz, ancak girişlerin ve çıkışların açıklamalarını güncelleştirebilirsiniz. Bu sayfadaki tüm içerik doğrudan yüklenen API spesifikasyonundan alınır.

4. Gerekirse, açıklamaları güncelleyin. Açıklamalar, değerlerin ne için kullanıldığına ilişkin bir tanım sağlar. Açıklamalardan herhangi biri boşsa, ilerlemeden önce bunları tamamlamanız gerekir. Daha iyi bir açıklamanız yoksa, ismi yapıştırın.

5. Açıklamaları tamamladıktan sonra Sonraki'yi seçin.

   İlk araç yapılandırılır ve Eklenti aracınızı seçin ve yapılandırın sayfasındaki Seçili araçlar listesinde görünür.

   

6. API'den şu anda eklemek istediğiniz diğer araçları ekleyin. Temsilcinizin desteklemesini istediğiniz araçları eklemeyi bitirdiğinizde İleri'yi seçin.

   Aracınızı gözden geçirin sayfası görüntülenir. Sayfa, yapılandırılmış REST API aracının ayrıntılarını sağlar.

   

İnceleme ve yayımlama

1. Herhangi bir güncelleştirme yapmanız gerekiyorsa Geri'yi seçin ve değişikliklerinizi yapın. Aksi takdirde İleri'yi seçin.

   İşlem devam ederken aracının yayımlandığını gösteren bir ekran görüntülenir. Yayımlama işlemi tamamlandığında bilgilendirilirsiniz.

2. Devam etmek için Bağlantı oluştur seçeneğini seç. Ekleme aracı ekranına geri döndürüldünüz.

3. Araç tipi seçicisinde REST API'yi seçin. API'nizden yeni oluşturulan araçları görebilirsiniz. API'den eklediğiniz her araç için bir giriş olmalı.

4. API'den yeni yapılandırılan araçların her biri için API'ye bir bağlantı oluşturun veya seçin ve aracınıza ekleyin:

   1. Ekle araç ekranında aracı seçin.
   2. Bağlantı altından mevcut bir bağlantıyı seçin veya Yenibağlantı oluştur seçeneğini seçin.
   3. Bağlantı için gereken bilgileri girin ve ardından Oluştur'u seçerek araçla bağlantıyı oluşturun.
   4. Ekle seçeneğini seçin ve aracı ajanınıza eklemek için configure yapın.

   

REST API'deki araçlar artık ajanınızda kullanılabilir.

Tip

Aracınızı daha kolay bulmak için, Arama çubuğunu bulmak için kullanın.