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

[Bu makale, yayın öncesi belgelerine dahildir ve değiştirilebilir.]

Oluşturduğunuz bir aracı harici sistemlere bağlamak ve aracınız içerisinde kullanım için mevcut verilere erişmek için REST API'leri (OpenAI API dahil) kullanabilirsiniz. Copilot Studio'e üç şeyi sağlayarak aracınızı bir REST API'ye bağlayabilirsiniz:

• 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

REST API'leri Copilot aracılarına ve özel aracılara Copilot Studio aracılığıyla eklenebilir.

Önemli

Bu madde, Microsoft Copilot Studio önizleme belgelerini içerir ve değişikliğe tabidir.

Önizleme özellikleri üretim kullanımına 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, Microsoft Copilot Studio Genel Bakış'a bakın.

Copilot aracıları, bir oluşturucunun bağlayıcılar, API'ler, istemler ve bilgi kaynakları gibi birden çok veri kaynağını tek bir aracısında birleştirmesine olanak tanır. Bu aracıyı Microsoft 365 Copilot gibi Microsoft markalı aracı deneyimlerini genişletmek için kullanabilirsiniz.

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

Not

REST API araçları bir OpenAPI v2 belirtiminden oluşturulmalıdır. Bu gereksinim, Power Platform'un API belirtimlerini işleme davranışından kaynaklanır. Bir v3 belirtimi gönderilirse, oluşturma işlemi sırasında otomatik olarak bir v2 belirtimine çevrilir.

Önkoşullar

Bağlayıcı eylemleriyle Microsoft markalı aracı deneyimlerini genişletmek için birkaç önkoşul gerekir.

Tüm aracı deneyimi türleri için, oluşturucu düzeyinde kimlik bilgilerine ve Copilot Studio lisansına sahip olmanız gerekir.

Ayrıca, OpenAPI spesifikasyonunun bir kopyasına, ihtiyaç duyulan kimlik doğrulama türü bilgisine ve kimlik doğrulama ayrıntılarına da ihtiyacınız olacak.

Bir aracıya REST API eylemi ekleyin

Aracı sitenize bir REST API eklemek birkaç adımdan oluşur. Aşağıdaki bölümler sizi bu süreçte yönlendirecektir.

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

Süreçte birkaç adım var.

Aracıya eylem ekleme

1. Aracınızın 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.

   Araç ekle sayfası görüntülenir.

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

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

1. Bağlanmak istediğiniz REST API için bir OpenAPI belirtim dosyası yükleyin. Belirtim dosyasını REST API'yi karşıya yükle ekranına sürükleyip bırakabilir veya kullanmak istediğiniz dosyayı bulmak için sisteminize göz atabilirsiniz.

   

   Not

   OpenAPI belirtimi, v2 biçiminde bir JSON dosyası olmalıdır. Bir v3 belirtimi gönderilirse, oluşturma işlemi sırasında otomatik olarak bir v2 belirtimine çevrilir.

   Belirtimi karşıya yükledikten sonra ekran, belirtim dosyası adını ve ayrıntıları gösterecek şekilde güncelleştirilir.

   

   Sonraki adımlarda, prosedürü bir ADO bilet yönetim sistemi olan SunnyADO'nun belirli bir örneğine dayandırıyoruz. Örnekte amaç, kullanıcıların biletlerini aracı aracılığıyla almalarına ve güncellemelerine izin vermektir.

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

   API hakkında ek bilgi sağlayabileceğiniz bir API eklentisi ayrıntıları sayfası sunulur.

   

   Açıklama alanı başlangıçta yüklediğiniz API spesifikasyonundaki 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. Aracınızın seçim sürecine yardımcı olmak için, eşanlamlıları da içeren 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ümlerin ne olduğu hakkında daha fazla bilgi için Çözüm kavramları'na bakın.

   

   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, sizin için eylem adı ve varsayılan yayımcıyla bir çözüm oluşturulur. Eyleminizi bir çözümde depolamak, eyleminizi kolay bir şekilde ortamlar arasında taşımanıza olanak sağlar.

   Not

   Varsayılan çözümü veya CDS varsayılan çözümünü bu durumda bir seçenek olarak görmüyorsanız, kolay yönetim için özel bir çözüme sahip olmanızı öneririz. 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 ayrıntılarını sağlayın

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

Not

Şu anda mevcut seçenekler Hiçbiri, Kimlik Doğrulama 2.0 ve API'dir.

1. Listeden bir kimlik doğrulama yöntemi seçin.

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

   • Hiçbiri: Başka bir alan gerekli değildir.
   • API Anahtarı:
     • Parametre Etiketi: API parametresi için bir metin etiketi.
     • Parametre Adı: API parametresi için bir metin adı.
     • Parametre Konumu: Parametrenin bulunabileceği konumdur.
   • Kimlik Doğrulaması 2.0:
     • İstemci Kimliği: Hedef hizmetin istemci GUID'si.
     • Gizli Anahtar – İstemci için gizli dizi değeri. Kullanıcı daha sonra düzenleme panelini açtığında gizli dizi görüntülenmez. Ancak, daha fazla düzenleme yapmayı seçerseniz buna ihtiyacınız olacağından gizli anahtarı depolayın.
     • Yetkilendirme URL'si: Kaynak sistemi yetkilendirmek için kullanılan URL.
     • Belirteç URL'si: Belirtecin alınabileceği URL.
     • Yenileme URL'si: Yenileme senaryosunda yönlendirildiğiniz URL.
     • Kapsam: Microsoft Entra uygulamaları için API'ye atanan Kapsam URL'si.
     • Hangi Microsoft 365 kuruluş uç noktalara erişir: Bu, kaynağa erişimi üreticinin kuruluşuyla veya tüm kuruluşlarla sınırlar.
     • Uç noktaları hangi uygulama (İstemci) kullanabilir: Bu verilere erişmek için kullanılabilecek istemci sistemini tanımlayan GUID. Uygulamalar Microsoft 365, Power Automate ve diğer seçenekleri içerebilir.

3. Tüm alanlar tamamlandıktan sonra İleri'yi seçin.

   Api için etkinleştirebileceğiniz araçları seçebileceğiniz eklenti aracınızı seçin ve yapılandırın sayfası sunulur.

   

API için araçları seçme

Etkinleştirmek için API tarafından desteklenen araçları seçin. Genel olarak REST API, API belirtiminde tanımlanan uç nokta ve HTTP yönteminin (get, put, post, delete vb.) çeşitli bileşimleri aracılığıyla bir dizi araç 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 belirtiminiz güncelleştirme ve silme eylemlerini içerebilir, ancak yalnızca aracı kullanıcılarınızın kayıt oluşturabilmesini istersiniz.

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

   Eklenti eyleminizi yapılandırın sayfası görüntülenir.

   

2. Seçili eylemi yapılandırın. Genel API'de olduğu gibi bir Araç adı ve Araç açıklaması sağlamanız istenir. Açıklamalar başlangıçta API belirtimindeki açıklamalardan önceden doldurulur. Adın benzersiz olması gerekmez, ancak aracın kendisini temsil etmesi gerekir. Genel API açıklamasında olduğu gibi açıklama, sorgunuzun bu belirli araçla uyumlu olduğunu daha iyi tanımlamak için dil modeline ayrıntıları sağlayacak kadar özel olmalıdır.

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

   Aracının parametrelerini gözden geçir sayfası görüntülenir.

   

   Bu sayfa, olası giriş ve çıkış değerlerinin bir parçası olarak sağlanan değerleri gösterir. Bu değerler değiştirilemez, ancak girişlerin ve çıkışların açıklamaları güncellenebilir. Bu sayfadaki tüm içerik doğrudan yüklenen API spesifikasyonundan alınır.

4. Açıklamalar için değerleri gerektiği gibi doldurun. Açıklamalar, değerlerin ne için kullanıldığına ilişkin bir tanım sağlar. Açıklamalardan herhangi biri boşsa, ilerleyebilmeniz için önce tamamlanmaları gerekir. Daha iyi bir açıklamanız yoksa adı yapıştırabilirsiniz.

5. Açıklamaları tamamladıktan sonra İleri'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. Şu anda dahil etmek istediğiniz diğer işlemleri ekleyin. Aracınızın desteklemesini istediğiniz araçları eklemeyi tamamladıktan sonra İ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çip değişikliklerinizi yapabilirsiniz. Aksi halde İleri'yi seçin.

   İşlem tamamlanırken aletinizin yayımlandığını gösteren bir ekran gösterilir. Yayımlama işlemi tamamlandığında bilgilendirilirsiniz.

2. Yayımlama tamamlandıktan sonra Araç seçin ekranına geri dönersiniz . Burada, yeni yapılandırılan REST API'yi Copilot aracısı veya özel aracınıza ekleyebilir ve bileşenin yapılandırmasını tamamlayabilirsiniz.

   

REST API aracınız artık aracınızda kullanılabilir.

İpucu

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