Aracılığıyla paylaş

API başvurusu - Direct Line API 3.0

  • Makale

Direct Line API 3.0 kullanarak istemci uygulamanızın botunuzla iletişim kurmasını sağlayabilirsiniz. Direct Line API 3.0, HTTPS üzerinden endüstri standardı REST ve JSON kullanır.

Temel URI

Direct Line API 3.0'a erişmek için tüm API istekleri için şu temel URI'lerden birini kullanın:

  • Genel botlar için https://directline.botframework.com

  • Bölgesel bot için, seçili bölgeye göre aşağıdaki uri'yi girin:

    Bölge Temel URI
    Avrupa https://europe.directline.botframework.com
    Hindistan https://india.directline.botframework.com

İpucu

Bazı istekler coğrafi sınırların ötesine geçebileceğinden bölgesel bir bot için genel temel URI'yi kullanırsanız istek başarısız olabilir.

Üst Bilgiler

Standart HTTP isteği üst bilgilerine ek olarak, Doğrudan Satır API'sinin isteği veren istemcinin kimliğini doğrulamak için gizli dizi veya belirteç belirten bir üst bilgi içermesi Authorization gerekir. Authorization Üst bilgiyi şu biçimi kullanarak belirtin:

Authorization: Bearer SECRET_OR_TOKEN

İstemcinizin Doğrudan Hat API isteklerinin kimliğini doğrulamak için kullanabileceği gizli dizi veya belirteç alma hakkında ayrıntılı bilgi için bkz . Kimlik doğrulaması.

HTTP durum kodu

Her yanıtla birlikte döndürülen HTTP durum kodu, ilgili isteğin sonucunu gösterir.

HTTP durum kodu Anlamı
200 İstek başarılı oldu.
201 İstek başarılı oldu.
202 İstek işlenmek üzere kabul edildi.
204 İstek başarılı oldu, ancak hiçbir içerik döndürülmedi.
400 İstek yanlış biçimlendirilmiş veya başka bir şekilde yanlış.
Kategori 401 İstemcinin isteği yapma yetkisi yok. Bu durum kodu genellikle üst bilgi eksik veya hatalı biçimlendirilmiş olduğundan Authorization oluşur.
Kategori 403 İstemcinin istenen işlemi gerçekleştirmesine izin verilmiyor. İşlem aşağıdaki nedenlerle başarısız olabilir.
  • Geçersiz bir belirteç: İstek daha önce geçerli olan ancak süresi dolmuş bir belirteç kullandığında code ErrorResponse nesnesi içinde döndürülen Error özelliğini olarak ayarlanırTokenExpired.
  • Veri sınırı ihlali: Botunuz bölgesel bir botsa ancak Temel URI bölgesel değilse, bazı istekler coğrafi sınırların ötesine geçebilir.
  • Geçersiz bir hedef kaynak: Hedef bot veya site geçersiz veya silinmiş.
404 İstenen kaynak bulunamadı. Bu durum kodu genellikle geçersiz bir istek URI'si olduğunu gösterir.
500 Direct Line hizmetinde bir iç sunucu hatası oluştu.
502 Bot kullanılamıyor veya bir hata döndürdü. Bu yaygın bir hata kodudur.

Not

Http durum kodu 101, WebSocket bağlantı yolunda kullanılır, ancak bu büyük olasılıkla WebSocket istemciniz tarafından işlenir.

Hatalar

4xx aralığında veya 5xx aralığında bir HTTP durum kodu belirten herhangi bir yanıt, yanıtın gövdesinde hata hakkında bilgi sağlayan bir ErrorResponse nesnesi içerir. 4xx aralığında bir hata yanıtı alırsanız, hatanın nedenini belirlemek için ErrorResponse nesnesini inceleyin ve isteği yeniden göndermeden önce sorununuzu çözün.

Not

ErrorResponse nesnesinin code içindeki özelliğinde belirtilen HTTP durum kodları ve değerleri kararlıdır. ErrorResponse nesnesinin içindeki özelliğinde message belirtilen değerler zaman içinde değişebilir.

Aşağıdaki kod parçacıkları örnek bir isteği ve sonuçta elde edilen hata yanıtını gösterir.

İste

POST https://directline.botframework.com/v3/directline/conversations/abc123/activities
[detail omitted]

Response

HTTP/1.1 502 Bad Gateway
[other headers]

{
    "error": {
        "code": "BotRejectedActivity",
        "message": "Failed to send activity: bot returned an error"
    }
}

Belirteç işlemleri

İstemcinin tek bir konuşmaya erişmek için kullanabileceği bir belirteç oluşturmak veya yenilemek için bu işlemleri kullanın.

Operasyon Açıklama
Belirteç Oluştur Yeni bir konuşma için belirteç oluşturma.
Yenileme Belirteci Belirteci yenileyin.

Belirteç Oluştur

Bir konuşma için geçerli olan bir belirteç oluşturur.

POST /v3/directline/tokens/generate
İçerik Açıklama
İstek gövdesi TokenParameters nesnesi
İadeler Konuşma nesnesi

Yenileme Belirteci

Belirteci yeniler.

POST /v3/directline/tokens/refresh
İçerik Açıklama
İstek gövdesi yok
İadeler Konuşma nesnesi

Konuşma işlemleri

Botunuzla bir konuşma açmak ve istemci ile bot arasında etkinlik alışverişi yapmak için bu işlemleri kullanın.

Operasyon Açıklama
Konuşmayı Başlat Botla yeni bir konuşma açar.
Konuşma Bilgilerini Alma Mevcut bir konuşma hakkında bilgi alır. Bu işlem, istemcinin konuşmaya yeniden bağlanmak için kullanabileceği yeni bir WebSocket akış URL'si oluşturur.
Etkinlik Alma Bottan etkinlikleri alır.
Etkinlik Gönder Bota bir etkinlik gönderir.
Dosyaları Karşıya Yükleme ve Gönderme Dosyaları karşıya yükler ve ek olarak gönderir.

Konuşmayı Başlat

Botla yeni bir konuşma açar.

POST /v3/directline/conversations
İçerik Açıklama
İstek gövdesi TokenParameters nesnesi
İadeler Konuşma nesnesi

Konuşma Bilgilerini Alma

Mevcut bir konuşma hakkında bilgi alır ve ayrıca istemcinin konuşmaya yeniden bağlanmak için kullanabileceği yeni bir WebSocket akış URL'si oluşturur. İsteğe bağlı olarak istemci tarafından görülen en son iletiyi belirtmek için istek URI'sinde parametresini belirtebilirsiniz watermark .

GET /v3/directline/conversations/{conversationId}?watermark={watermark_value}
İçerik Açıklama
İstek gövdesi yok
İadeler Konuşma nesnesi

Etkinlik Alma

Belirtilen konuşma için bottan etkinlikleri alır. İsteğe bağlı olarak istemci tarafından görülen en son iletiyi belirtmek için istek URI'sinde parametresini belirtebilirsiniz watermark .

GET /v3/directline/conversations/{conversationId}/activities?watermark={watermark_value}
İçerik Açıklama
İstek gövdesi yok
İadeler ActivitySet nesnesi. Yanıt, nesnesinin ActivitySet bir özelliği olarak içerirwatermark. İstemciler, hiçbir etkinlik döndürülene kadar değeri ilerleterek kullanılabilir etkinliklere watermark sayfalama yapmalıdır.

Etkinlik Gönder

Bota bir etkinlik gönderir.

POST /v3/directline/conversations/{conversationId}/activities
İçerik Açıklama
İstek gövdesi Activity nesnesi
İadeler Bota gönderilen Etkinliğin kimliğini belirten bir özellik içeren ResourceResponseid.

Dosyaları Karşıya Yükleme ve Gönderme

Dosyaları karşıya yükler ve ek olarak gönderir. ekleri userId gönderen kullanıcının kimliğini belirtmek için istek URI'sindeki parametresini ayarlayın.

POST /v3/directline/conversations/{conversationId}/upload?userId={userId}
İçerik Açıklama
İstek gövdesi Tek bir ek için istek gövdesini dosya içeriğiyle doldurun. Birden çok ek için, her ek için bir bölüm içeren çok bölümlü bir istek gövdesi oluşturun ve ayrıca (isteğe bağlı olarak) belirtilen ekler için kapsayıcı olarak görev yapması gereken Activity nesnesi için bir bölüm oluşturun. Daha fazla bilgi için bkz . Bota etkinlik gönderme.
İadeler Bota gönderilen Etkinliğin kimliğini belirten bir özellik içeren ResourceResponseid.

Not

Karşıya yüklenen dosyalar 24 saat sonra silinir.

Şema

Direct Line 3.0 şeması, Bot Framework şeması tarafından tanımlanan tüm nesnelerin yanı sıra Doğrudan Çizgi'ye özgü bazı nesneleri içerir.

ActivitySet nesnesi

Bir etkinlik kümesini tanımlar.

Özellik Türü Açıklama
Faaliyetleri Etkinlik[] Etkinlik nesneleri dizisi.
Filigran Dize Küme içindeki etkinliklerin en büyük filigranı. İstemci, bottan etkinlik alırken veya yeni bir WebSocket akış URL'si oluştururken gördüğü en son iletiyi belirtmek için değerini kullanabilirwatermark.

Konuşma nesnesi

Bir Direct Line konuşması tanımlar.

Özellik Türü Açıklama
conversationId Dize Belirtilen belirtecin geçerli olduğu konuşmayı benzersiz olarak tanımlayan kimlik.
Etag Dize HTTP ETag (varlık etiketi).
expires_in Numara Belirtecin süresi dolana kadar olan saniye sayısı.
referenceGrammarId Dize Bu bot için başvuru dil bilgisi kimliği.
streamUrl Dize Konuşmanın ileti akışının URL'si.
Belirte -ci Dize Belirtilen konuşma için geçerli olan belirteç.

TokenParameters nesnesi

Belirteç oluşturmaya yönelik parametreler.

Özellik Türü Açıklama
Etag Dize HTTP ETag (varlık etiketi).
trustedOrigins string[] Belirtecin içine katıştırmak için güvenilen kaynaklar.
kullanıcı ChannelAccount Belirtecin içine eklemek için kullanıcı hesabı.

Aktiviteler

Bir istemcinin Doğrudan Hat aracılığıyla bottan aldığı her Etkinlik için:

  • Ek kartları korunur.
  • Karşıya yüklenen eklerin URL'leri özel bir bağlantıyla gizlenir.
  • channelData özelliği değiştirilmeden korunur.

İstemciler bir ActivitySet'in parçası olarak bottan birden çok etkinlik alabilir.

bir istemci Doğrudan Hat aracılığıyla bota gönderdiğinde Activity :

  • özelliği, type gönderdiği tür etkinliğini belirtir (genellikle ileti).
  • from özelliği, istemci tarafından seçilen bir kullanıcı kimliğiyle doldurulmalıdır.
  • Ekler, Doğrudan Çizgi ek uç noktası aracılığıyla karşıya yüklenen mevcut kaynaklara veya URL'lere URL'ler içerebilir.
  • channelData özelliği değiştirilmeden korunur.
  • JSON ve şifrelenmiş olarak seri hale getirildiğinde etkinliğin toplam boyutu 256.000 karakteri aşmamalıdır. Etkinlikleri 150 binin altında tutmanızı öneririz. Daha fazla veri gerekiyorsa etkinliği bölmeyi veya ekleri kullanmayı göz önünde bulundurun.

İstemciler istek başına tek bir etkinlik gönderebilir.

Ek kaynaklar