Aracı SDK'sı (Önizleme)

Bot Framework / Microsoft Aracıları SDK Etkinlik yüklerini kullanıcı tarafından sağlanan aracı uç noktasına iletir. Aracı uç noktası URL'si çağrı başına giriş parametresi olarak sağlanır. Bağlantı oluşturulurken kimlik doğrulaması seçilir: kimlik doğrulaması yok, statik API anahtarı veya Microsoft Entra ID OAuth (client_credentials veya kullanıcı oturum açma). OAuth seçildiğinde taşıyıcı belirteç hedef kitlesinin (bağlantıda yapılandırılan Kaynak URL'si) hedef aracı tarafından beklenen hedef kitleyle eşleşmesi gerekir.

Bu bağlayıcı aşağıdaki ürün ve bölgelerde kullanılabilir:

Hizmet Class Regions
Copilot Studio Standart Aşağıdakiler dışında tüm Power Automate bölgeleri:
     - ABD Kamu (GCC)
     - US Government (GCC High)
     - 21Vianet tarafından işletilen Çin Bulutu
     - ABD Savunma Bakanlığı (DoD)
Logic Apps Standart Aşağıdakiler dışında tüm Logic Apps bölgeleri :
     - Azure Kamu bölgeleri
     - Azure Çin bölgeleri
     - ABD Savunma Bakanlığı (DoD)
Power Apps Standart Aşağıdakiler dışında tüm Power Apps bölgeleri:
     - ABD Kamu (GCC)
     - US Government (GCC High)
     - 21Vianet tarafından işletilen Çin Bulutu
     - ABD Savunma Bakanlığı (DoD)
Power Automate Standart Aşağıdakiler dışında tüm Power Automate bölgeleri:
     - ABD Kamu (GCC)
     - US Government (GCC High)
     - 21Vianet tarafından işletilen Çin Bulutu
     - ABD Savunma Bakanlığı (DoD)
Contact
İsim Microsoft
URL https://support.microsoft.com
Bağlayıcı Meta Verileri
Publisher Microsoft
Web Sitesi https://www.microsoft.com
Gizlilik ilkesi https://privacy.microsoft.com/
Kategoriler Verimli -lik

Aracı SDK bağlayıcısı, Bot Framework /Microsoft Aracılar SDK Etkinlik yüklerini kullanıcı tarafından sağlanan aracı uç noktasına iletir. Aracı uç noktası URL'si çağrı başına giriş parametresi olarak sağlanır. Bağlantı, bağlayıcının aracıda kimlik doğrulamasını seçer: kimlik doğrulaması yok, statik API anahtarı, yalnızca uygulama Microsoft Entra ID belirteci (istemci kimlik bilgileri) veya Microsoft Entra ID temsilci kullanıcı belirteci (kullanıcı oturum açma). Her iki Microsoft Entra ID seçeneği için de taşıyıcı belirteci hedef kitlesinin (bağlantıda yapılandırılan Kaynak URL'si) hedef aracı tarafından beklenen hedef kitleyle eşleşmesi gerekir.

Prerequisites

  • DAĞıTılan Microsoft Aracıları SDK'sı / Bot Framework aracısı HTTPS üzerinden erişilebilir.
  • Microsoft Entra ID (istemci kimlik bilgileri) için: aracıyı barındıran kiracıda kayıtlı, hedef aracıyı çağırma izni ve izniyle client_credentials yapılandırılmış bir Microsoft Entra ID uygulaması.
  • Microsoft Entra ID için (kullanıcı oturum açma): aracının istemci gizli dizisine sahip kendi Microsoft Entra ID uygulaması (Microsoft Uygulama Kimliği), kullanıcıların onay verebileceği kullanıma açık bir API kapsamı, Microsoft Graph User.Read ("Oturum aç ve kullanıcı profilini oku"), izinle temsilci izni verdi ve https://global.consent.azure-apim.net/redirect/agentsdkWeb yeniden yönlendirme URI'si olarak eklendi.
  • API anahtarı ve istemci kimlik bilgileri seçenekleri için, aracının beklenen belirteç hedef kitlesi (genellikle aracının Microsoft Uygulama Kimliği, örneğin api://<appId> Uygulama Kimliği GUID'si). Kullanıcı oturum açma için hedef kitlenin Uygulama Kimliği GUID'si olması gerekir (aşağıya bakın).

Kimlik bilgilerinizi alma

Microsoft Entra ID (istemci kimlik bilgileri)

Bağlayıcı yalnızca uygulama belirteci gönderir. API isteklerinizin kimliğini doğrulamak için şunları yapmanız gerekir:

  1. Microsoft Entra ID uygulamasının Kiracı Kimliği.
  2. Microsoft Entra ID uygulamasının İstemci Kimliği (Uygulama Kimliği).
  3. Bu uygulama için İstemci Gizli Anahtarı .
  4. Hedef aracı tarafından beklenen hedef kitleyle eşleşen Kaynak URL'si (Bot Framework beceri kimlik doğrulaması deseni).

Bağlantı oluştururken bu değerleri sağlayın. hedef kitleler farklıysa aracı başına bir bağlantı oluşturun.

Microsoft Entra ID (kullanıcı oturum açma)

Bağlayıcı, bağlantıda oturum açmış hesabın temsilci belirtecini gönderir, böylece aracı bu hesabın adına değiştirebilir (örneğin, Microsoft 365 Aracıları SDK'sı ConnectorUserAuthorization işleyicisi ile). Gerekenler:

  1. Aracının Microsoft Entra ID uygulamasının Kiracı Kimliği.
  2. İstemci Kimliği: aracının kendi Microsoft Uygulama Kimliği. Microsoft 365 Aracıları SDK'sı, belirteci yalnızca belirtecin aracının kendi uygulamasına verilmesiyle kullanıcı adına değiştirir.
  3. Bu uygulama için İstemci Gizli Anahtarı .
  4. Kaynak URL'si: aracının Microsoft Uygulama Kimliği (GUID), İstemci Kimliği ile aynı değer. Aracının kendi uygulaması hem istemci hem de kaynak olduğundan, Microsoft Entra burada GUID gerektirir (aksi AADSTS90009); api://<appId> bu seçenek için desteklenmez.

Bağlantı oluştururken bu değerleri sağlayın ve ardından oturum açıp aracının kullanıma sunulan kapsamına onay verin. Aracı başına bir bağlantı oluşturun.

Uygulamanın ayrıca izinle Microsoft Graph User.Read ("Oturum aç ve kullanıcı profilini oku") temsilci iznine de ihtiyacı vardır; onay olmadan oturum açma işlemi AADSTS90008 başarısız olur.

Aşağı akış API'sinin belirtecini değiştirmek için bu API'nin aracının uygulamasındaki temsilci izinlerini yapılandırın ve gerekli kullanıcı veya yönetici onayını alın. Bir kapsamı aracının kendi API'sinde ortaya çıkarmak aşağı akış izinleri vermez.

Bilinen sorunlar ve sınırlamalar

  • Giriş agentEndpoint tam bir HTTPS URL'si olmalıdır (örneğin, https://my-agent.azurewebsites.net). Bağlayıcı Etkinlik yükünü ekler /api/messages ve iletir.
  • Bağlayıcı Etkinlik yükü as-is iletir ve ayarlanmaz deliveryMode. Aracı, yanıt etkinliklerini gelen etkinlikte sağlanana geri serviceUrl göndererek zaman uyumsuz (normal teslim) yanıtlar (örneğin, Microsoft Copilot Studio, SAS anahtarlı bir geri serviceUrlçağırma sağlar).
  • Microsoft Entra ID (kullanıcı oturum açma) bağlantısı, aracıyla sohbet eden diğer kişiler adına yapılan aramalar da dahil olmak üzere bu bağlantıyla yapılan her çağrı için her zaman bağlantıda oturum açmış hesabın temsilci belirtecini gönderir. Her arayan için ayrı bir belirteç göndermez, bu nedenle etkinliğin from kullanıcısı belirteçteki kullanıcıdan farklı olabilir. İstekleri yalnızca doğrulanmış belirteçteki hesap olarak yetkileyin ve etkinliğin from veya istek üst bilgilerini sohbet eden kişinin yetkilisi olarak kabul etmeyin. Aracı, kendisiyle sohbet eden her kişi gibi davranması gerekiyorsa bu bağlantı türünü kullanmayın.
  • Oturum açmış hesabın onayı iptal edilirse veya oturumu artık yenilenemezse, bağlantıda yeniden oturum açın.
  • Bu bağlayıcı önizleme aşamasındadır. Kullanılabilirlik ve özellikler değiştirilebilir.

Bağlantı oluşturma

Bağlayıcı aşağıdaki kimlik doğrulama türlerini destekler:
API anahtarı Özel bir HTTP üst bilgisinde hedef aracının beklediği statik BIR API anahtarıyla kimlik doğrulaması yapın. Hem üst bilgi adını (örneğin, x-api-key) hem de değerini belirtin. Tüm bölgeler Paylaşılamaz
Microsoft Entra ID (istemci kimlik bilgileri) client_credentials akışını kullanan bir Microsoft Entra ID uygulamasından nane OAuth taşıyıcı belirteçleri. Taşıyıcı belirteç hedef kitlesi (Kaynak URL'si), hedef aracı tarafından beklenen hedef kitleyle eşleşmelidir. Tüm bölgeler Paylaşılamaz
Microsoft Entra ID (kullanıcı oturum açma) Hedef aracının Microsoft Entra ID uygulaması (yetkilendirme kodu akışı) aracılığıyla oturum açın ve oturum açmış hesabın temsilci taşıyıcı belirtecini gönderin. Bu bağlantıyla yapılan her çağrıda, aracıyla sohbet eden kişi değil, bağlantıda oturum açmış olan hesap kullanılır. Belirteci kullanıcı adına değiştirmek için aracının aşağı akış temsilci izinleri ve onayının yapılandırılması gerekir. Tüm bölgeler Paylaşılamaz
Kimlik doğrulaması yok Herhangi bir kimlik doğrulama üst bilgisi olmadan hedef aracı uç noktasını çağırın. Bunu yalnızca anonim çağrıları açıkça kabul eden aracılarla kullanın. Tüm bölgeler Paylaşılabilir
Varsayılan [KULLANIM DIŞI] Bu seçenek yalnızca açık kimlik doğrulama türü olmayan eski bağlantılar içindir ve yalnızca geriye dönük uyumluluk için sağlanır. Tüm bölgeler Paylaşılamaz

API anahtarı

Kimlik Doğrulama Kimliği: apiKey

Geçerli: Tüm bölgeler

Özel bir HTTP üst bilgisinde hedef aracının beklediği statik BIR API anahtarıyla kimlik doğrulaması yapın. Hem üst bilgi adını (örneğin, x-api-key) hem de değerini belirtin.

Bu, paylaşılabilir bir bağlantı değildir. Power app başka bir kullanıcıyla paylaşılıyorsa, başka bir kullanıcıdan açıkça yeni bağlantı oluşturması istenir.

İsim Türü Description Zorunlu
API anahtarı üst bilgi adı string Hedef aracının API anahtarını beklediği HTTP üst bilgisinin adı (örneğin, x-api-key veya Ocp-Apim-Subscription-Key). True
API anahtar değeri securestring Hedef aracı uç noktasına gönderilen her istekte gönderilen statik API anahtar değeri. True

Microsoft Entra ID (istemci kimlik bilgileri)

Kimlik Doğrulama Kimliği: oauthClientCredentials

Geçerli: Tüm bölgeler

client_credentials akışını kullanan bir Microsoft Entra ID uygulamasından nane OAuth taşıyıcı belirteçleri. Taşıyıcı belirteç hedef kitlesi (Kaynak URL'si), hedef aracı tarafından beklenen hedef kitleyle eşleşmelidir.

Bu, paylaşılabilir bir bağlantı değildir. Power app başka bir kullanıcıyla paylaşılıyorsa, başka bir kullanıcıdan açıkça yeni bağlantı oluşturması istenir.

İsim Türü Description Zorunlu
Tenant string Microsoft Entra ID uygulamasının kiracı kimliği True
Müşteri Kimliği string Microsoft Entra ID uygulamasının istemci (veya uygulama) kimliği. True
İstemci Parolası securestring Microsoft Entra ID uygulamasının istemci gizli dizisi. True
Kaynak URL string OAuth belirtecinin hedef kitlesi. Genellikle hedef aracının Microsoft Uygulama Kimliği (örneğin, api://< appId> veya Uygulama Kimliği GUID'si). True

Microsoft Entra ID (kullanıcı oturum açma)

Kimlik Doğrulama Kimliği: oauthAuthorizationCode

Geçerli: Tüm bölgeler

Hedef aracının Microsoft Entra ID uygulaması (yetkilendirme kodu akışı) aracılığıyla oturum açın ve oturum açmış hesabın temsilci taşıyıcı belirtecini gönderin. Bu bağlantıyla yapılan her çağrıda, aracıyla sohbet eden kişi değil, bağlantıda oturum açmış olan hesap kullanılır. Belirteci kullanıcı adına değiştirmek için aracının aşağı akış temsilci izinleri ve onayının yapılandırılması gerekir.

Bu, paylaşılabilir bir bağlantı değildir. Power app başka bir kullanıcıyla paylaşılıyorsa, başka bir kullanıcıdan açıkça yeni bağlantı oluşturması istenir.

İsim Türü Description Zorunlu
Tenant string Hedef aracının Microsoft Entra ID uygulamasının kiracı kimliği. True
Müşteri Kimliği string Hedef aracının Microsoft Uygulama Kimliği. Aracının temsilci belirtecini kullanıcı adına değiş tokuş edebilmesi için aracının kendi uygulamasını kullanın. True
İstemci Parolası securestring Hedef aracının Microsoft Entra ID uygulamasının istemci gizli dizisi. True
Kaynak URL string Temsilci olarak atanan belirtecin hedef kitlesi. Hedef aracının Microsoft Uygulama Kimliği (GUID) olmalıdır ve İstemci Kimliği ile aynı değer olmalıdır: Microsoft Entra bir uygulama kendisi için belirteç istediğinde yalnızca GUID'yi kabul eder. True

Kimlik doğrulaması yok

Kimlik Doğrulama Kimliği: anonim

Geçerli: Tüm bölgeler

Herhangi bir kimlik doğrulama üst bilgisi olmadan hedef aracı uç noktasını çağırın. Bunu yalnızca anonim çağrıları açıkça kabul eden aracılarla kullanın.

Bu, paylaşılabilir bir bağlantıdır. Power app başka bir kullanıcıyla paylaşılıyorsa, bağlantı da paylaşılır. Daha fazla bilgi için bkz. tuval uygulamaları için Connectors'a genel bakış - Power Apps | Microsoft Docs

Varsayılan [KULLANIM DIŞI]

Geçerli: Tüm bölgeler

Bu seçenek yalnızca açık kimlik doğrulama türü olmayan eski bağlantılar içindir ve yalnızca geriye dönük uyumluluk için sağlanır.

Bu, paylaşılabilir bir bağlantı değildir. Power app başka bir kullanıcıyla paylaşılıyorsa, başka bir kullanıcıdan açıkça yeni bağlantı oluşturması istenir.

Eylemler

Aracıya etkinlik gönderme

Etkinlik Protokolü yükünü {agentEndpoint}/api/messages konumundaki aracı uç noktasına iletir. Bağlantı Microsoft Entra ID OAuth kullandığında, belirteç hedef kitlesi (bağlantıdaki Kaynak URL'si) hedef aracı tarafından beklenen hedef kitleye eşit olmalıdır (Bot Framework beceri kimlik doğrulaması düzeni); hedef kitleler farklıysa aracı başına bir bağlantı oluşturun. Bağlayıcı Etkinlik yükünü as-is iletir ve 'deliveryMode' öğesini ayarlamaz; aracı, gelen etkinlikte sağlanan 'serviceUrl' öğesine yanıt etkinlikleri sunarak zaman uyumsuz (normal teslim) yanıtlar.

Aracıya etkinlik gönderme

İşlem Kimliği:
SendActivity

Etkinlik Protokolü yükünü {agentEndpoint}/api/messages konumundaki aracı uç noktasına iletir. Bağlantı Microsoft Entra ID OAuth kullandığında, belirteç hedef kitlesi (bağlantıdaki Kaynak URL'si) hedef aracı tarafından beklenen hedef kitleye eşit olmalıdır (Bot Framework beceri kimlik doğrulaması düzeni); hedef kitleler farklıysa aracı başına bir bağlantı oluşturun. Bağlayıcı Etkinlik yükünü as-is iletir ve 'deliveryMode' öğesini ayarlamaz; aracı, gelen etkinlikte sağlanan 'serviceUrl' öğesine yanıt etkinlikleri sunarak zaman uyumsuz (normal teslim) yanıtlar.

Parametreler

Veri Akışı Adı Anahtar Gerekli Tür Description
Aracı uç noktası URL'si
 agentEndpoint True string

Hedef Microsoft Aracıları SDK'sının / Bot Framework uç noktasının temel URL'si (örneğin, https://my-agent.azurewebsites.net). Bağlayıcı /api/messages ekler.
object

Döndürülenler

response
object

Tanımlar

Obje

Bu , 'object' türüdür.