Aracılığıyla paylaş

HTTP istekleri oluşturma

  • Makale

Önemli

Power Virtual Agents yetenekleri ve özellikleri, Microsoft Copilot genelinde üretken yapay zekaya ve gelişmiş tümleştirmelere yapılan önemli yatırımların ardından artık Microsoft Copilot Studio'nun parçasıdır.

Bazı makalelerde ve ekran görüntülerinde, belgeler ve eğitim içeriği güncelleştirilirken Power Virtual Agents'a başvurulabilir.

Copilot Studio'da, HTTP isteği düğümünü kullanarak harici REST API'lerini arayarak yardımcı pilotun yeteneklerini genişletebilirsiniz. Bu yöntem, harici bir sistemden veri almanız veya sistemdeki verileri değiştirmeniz gerektiğinde yararlı olabilir.

Önkoşullar

HTTP isteği düğümünü kullanma

  1. Düğüm ekle'yi (+) seçin. Gelişmiş alt menüsünü açın ve ardından HTTP isteği gönder'i seçin.

    Gelişmiş menüde HTTP isteği gönder seçeneğinin ekran görüntüsü.

  2. URL kutusuna, çağırmak istediğiniz API uç noktasının URL'sini girin.

  3. Açılır menüden uygun istek Yöntemini seçin. GET, POST, PATCH, PUT ve DELETE yöntemleri desteklenmektedir.

    Tamamlanmış API URL'si ve yöntem açılır menüsünün ekran görüntüsü

  4. Düğümdeki Başlıklar ve gövde alanından Düzenle düğmesine tıklayın. Bu eylemle, HTTP isteği özellikleri bölmesini açılır.

  5. Dilerseniz, HTTP isteğine bir veya daha fazla başlık ekleyebilirsiniz. Her başlığın anahtarını ve değerini eklemek için Ekle düğmesine tıklayın.

    HTTP düğümü için başlıklar anahtar-değer çifti listesinin ekran görüntüsü.

  6. Varsayılan olarak, HTTP isteğinin gövdesine içerik gönderilmez ancak gövdeye gönderilecek içeriği belirtebilirsiniz.

  7. Düğümde, kullanılabilir seçeneklerden Yanıt veri türü'nü seçin.

    Örnek bir JSON yanıtı sağlayabilirsiniz (bunu genellikle, çağırdığınız API'nin belgelerinde bulabilirsiniz). Bu yanıt, Power FX düzenleyicisinde IntelliSense desteğiyle yazma tuvalinizde başka yerlerde kullanabileceğiniz, türü kesin olarak belirlenmiş bir Power FX değişkeni oluşturur. Bunu yapmak için, Örnek Veriden öğesini seçin ve ardından Örnek JSON'dan şemayı al'a tıklayın. Örnek yanıtınızı gösterilen düzenleyiciye yapıştırıp Onayla'yı seçin.

    Örnek JSON'dan şemayı al düzenleyicisinin ekran görüntüsü.

  8. Yanıtı farklı kaydet alanında, yeni bir değişken oluşturarak veya var olan değişkenlerden birini seçerek HTTP isteği yanıtının depolanmasını istediğiniz konumu belirtin.

HTTP istek gövdesinde içerik gönderme

  1. Düğümdeki Başlıklar ve gövde alanından Düzenle düğmesine tıklayın. Bu eylemle, HTTP isteği özellikleri bölmesini açılır.

  2. Gövde altında, uygun içerik türünü seçin. Bu, varsayılan olarak İçerik Yok seçeneğine ayarlanmıştır. GET isteğiyle en sık kullanılan bu seçenekle, istek gövdesinde içerik bulunmaz. Gövdeye içerik eklemek için, kullanılabilir seçeneklerden birini belirleyin.

    Gövde içeriği seçenekleri açılır menüsünün ekran görüntüsü

    • JSON İçeriği: JSON içeriği, istek gövdesine JSON nesnesi sağlamanıza olanak tanır. Bu, genellikle POST veya PUT istekleri oluştururken kullanılır. Bu seçenek belirlendiğinde, JSON içeriğinizi girebileceğiniz bir düzenleyici sunulur.

      Ayrıca, Power FX kullanarak JSON içeriğinizi belirtebilir ve böylece dinamik değerler ve başvuru değişkenleri ekleyebilirsiniz. Bunu yapmak için, sırayla JSON'ı düzenle ve Formül düğmelerini seçip bir Power FX nesnesi girin (daha önce girilmiş var olan herhangi bir JSON sizin için Power FX nesnesine dönüştürülür). Bu nesne, HTTP isteği yapıldığında JSON'a dönüştürülür.

      Gövde içerik türü için seçilen JSON içeriğinin ekran görüntüsü.

    • Ham içerik: Ham içerik istek gövdesine bir veri dizesi eklemenize olanak tanır. Bu dize, belirttiğiniz herhangi bir içerik türü olabilir. Ham içerik aşağıdaki örnekte gösterilen dize içeriği gibi, bir Power FX formülü kullanılarak girilir.

      Gövde içerik türü için seçilen RAW içeriğin ekran görüntüsü.

Hata işleme ve zaman aşımı

HTTP isteği düğümünde, HTTP isteğinin başarısız olduğu veya hata döndürdüğü durumları çözmek için çeşitli seçenekler bulunur.

Varsayılan olarak bu özellik "Hata ver" seçeneğine ayarlanmıştır. Bu, bir HTTP isteği hata döndürdüğünde veya yürütemediğinde, yardımcı pilotun çalışmasını durduracağı ve Hata sistem konusunu tetikleyerek bir hata iletisi görüntüleyeceği anlamına gelir.

Ancak hata işleme özelliğini Hata sistem konusunu tetiklemeyip bunun yerine, belirttiğiniz değişkenlerde HTTP durum kodu ve hata yanıtı gövdesini dolduracak şekilde yapılandırabilirsiniz. Bu yapılandırma, bu değişkenleri konunun çalışmaya devam edebilmesi için gerektiği gibi araştırmanıza olanak tanır. Bu, yardımcı pilotun belirli bir HTTP isteği başarısız olsa bile çalışmaya devam etmesini istediğiniz senaryolarda yararlıdır.

Hata işleme davranışını yapılandırmak için:

  1. Düğümdeki Başlıklar ve gövde alanından Düzenle düğmesine tıklayın. Bu eylemle, HTTP isteği özellikleri bölmesini açılır.

  2. Hata işleme açılır menüsünden istediğiniz davranışı seçin.

  3. Hatada devam et'i seçerseniz, yeni değişkenler oluşturarak veya seçicide bulunan değişkenler arasından seçim yaparak Durum kodu ve Hata yanıtı gövdesi değişkenlerini yapılandırın.

    Durum kodu ve hata yanıtı gövdesi değişkenleri belirtilmiş olarak, hatada devam et seçeneğine yapılandırılmış hata işlemenin ekran görüntüsü.

Bu kod örneğinde, HTTP isteği başarısız olursa, yardımcı pilot HTTP durum kodunu Topic.StatusCode değişkeninde ve yanıt gövdesini Topic.ErrorResponse değişkeninde depolar. Böylece yardımcı pilot konuda sonraki adımlarına devam edecektir.

Hata yanıtı değişken türü Herhangi biri olmalıdır. Bunu bir Power Fx kaydına dönüştürmek için Ayrıştırma Değeri düğümü'nü kullanabilirsiniz.

Özellik bölmesinde ayrıca, milisaniye cinsinden bir değeri kabul eden bir İstek zaman aşımı özelliği de bulunur. Varsayılan değer 30 saniyedir ancak gerekirse bu değeri değiştirebilirsiniz.