Informazioni di riferimento sulle API: API Direct Line 3.0

È possibile consentire all'applicazione client di comunicare con il bot usando l'API Direct Line 3.0. L'API Direct Line 3.0 usa gli standard di settore REST e JSON tramite HTTPS.

URI di base

Per accedere all'API Direct Line 3.0, usare uno di questi URI di base per tutte le richieste API:

• Per i bot globali, usare https://directline.botframework.com

• Per un bot a livello di area immettere l'URI seguente in base all'area selezionata:

  Area	URI di base
  Europa	https://europe.directline.botframework.com
  India	https://india.directline.botframework.com

Intestazioni

Oltre alle intestazioni delle richieste HTTP standard, una richiesta all'API Direct Line deve includere un'intestazione Authorization che specifica un segreto o un token per l'autenticazione del client che invia la richiesta. Specificare l'intestazione Authorization usando questo formato:

Authorization: Bearer SECRET_OR_TOKEN

Per informazioni dettagliate su come ottenere un segreto o un token utilizzabile dal client per l'autenticazione delle richieste all'API Direct Line, vedere Autenticazione.

Codici di stato HTTP

Il codice di stato HTTP restituito con ogni risposta indica il risultato della richiesta corrispondente.

Errori

Nel corpo di qualsiasi risposta che specifica un codice di stato HTTP compreso nell'intervallo 4xx o 5xx sarà incluso un oggetto ErrorResponse contenente informazioni sull'errore. Se viene restituita una risposta di errore compresa nell'intervallo 4xx, controllare l'oggetto ErrorResponse per identificare la causa dell'errore e risolvere il problema prima di inviare di nuovo la richiesta.

I frammenti seguenti mostrano una richiesta di esempio e la risposta di errore risultante.

Richiedi

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

Risposta

HTTP/1.1 502 Bad Gateway
[other headers]

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

Operazioni relative ai token

Usare queste operazioni per creare o aggiornare un token utilizzabile da un client per accedere a una singola conversazione.

Generare token

Genera un token valido per una conversazione.

POST /v3/directline/tokens/generate

Aggiornare un token

Aggiorna il token.

POST /v3/directline/tokens/refresh

Operazioni riguardanti la conversazione

Usare queste operazioni per aprire una conversazione con il bot e scambiare attività tra il client e il bot.

Avviare la conversazione

Avvia una nuova conversazione con il bot.

POST /v3/directline/conversations

Ottenere informazioni su una conversazione

Ottiene informazioni su una conversazione esistente e genera anche un nuovo URL di flusso WebSocket che può essere usato da un client per riconnettersi a una conversazione. Facoltativamente, è possibile specificare il parametro watermark nell'URI della richiesta per indicare il messaggio più recente visualizzato dal client.

GET /v3/directline/conversations/{conversationId}?watermark={watermark_value}

Ottenere le attività

Recupera le attività dal bot per la conversazione specificata. Facoltativamente, è possibile specificare il parametro watermark nell'URI della richiesta per indicare il messaggio più recente visualizzato dal client.

GET /v3/directline/conversations/{conversationId}/activities?watermark={watermark_value}

Inviare un'attività

Invia un'attività al bot.

POST /v3/directline/conversations/{conversationId}/activities

Caricare e inviare file

Carica e invia file come allegati. Impostare il parametro userId nell'URI della richiesta per specificare l'ID dell'utente che invia gli allegati.

POST /v3/directline/conversations/{conversationId}/upload?userId={userId}

Schema

Lo schema di Direct Line 3.0 include tutti gli oggetti definiti dallo schema di Bot Framework, nonché alcuni oggetti specifici di Direct Line.

Oggetto ActivitySet

Definisce un set di attività.

Oggetto Conversation

Definisce una conversazione Direct Line.

Oggetto TokenParameters

Parametri per la creazione di un token.

Attività

Per ogni oggetto Activity che un client riceve da un bot tramite Direct Line:

• Le schede degli allegati vengono mantenute.
• Gli URL degli allegati caricati vengono nascosti con un collegamento privato.
• La proprietà channelData viene mantenuta senza modifiche.

I client possono ricevere più attività dal bot in un ActivitySet.

Quando un client invia un oggetto Activity a un bot tramite Direct Line:

• La type proprietà specifica l'attività di tipo che invia (in genere il messaggio).
• La proprietà from deve essere popolata con un ID utente scelto dal client.
• Gli allegati possono contenere URL di risorse esistenti o URL caricati tramite l'endpoint degli allegati di Direct Line.
• La proprietà channelData viene mantenuta senza modifiche.
• Le dimensioni totali dell'attività, se serializzata in JSON e crittografata, non devono superare i 256.000 caratteri. È consigliabile mantenere le attività sotto 150.000. Se sono necessari più dati, prendere in considerazione la suddivisione dell'attività o l'uso di allegati.

I client possono inviare un'unica attività per richiesta.

Risorse aggiuntive

• Specifiche delle attività di Bot Framework