Informazioni di riferimento sulle API - API Direct Line 3.0

È possibile abilitare l'applicazione client per comunicare con il bot usando Direct Line API 3.0. Direct Line API 3.0 usa rest e JSON standard del settore su 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 geografica	URI di base
  Europe	https://europe.directline.botframework.com
  India	https://india.directline.botframework.com

Intestazioni

Oltre alle intestazioni di richiesta HTTP standard, una richiesta API Direct Line deve includere un'intestazione Authorization che specifica un segreto o un token per autenticare il client che esegue 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 che il client può usare per autenticare le richieste API Direct Line, vedere Autenticazione.

Codici di stato HTTP

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

Errors

Qualsiasi risposta che specifica un codice di stato HTTP nell'intervallo 4xx o 5xx includerà un oggetto ErrorResponse nel corpo della risposta che fornisce informazioni sull'errore. Se viene visualizzata una risposta di errore nell'intervallo 4xx, esaminare l'oggetto ErrorResponse per identificare la causa dell'errore e risolvere il problema prima di inviare nuovamente la richiesta.

I frammenti di codice 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 token

Usare queste operazioni per creare o aggiornare un token che un client può usare per accedere a una singola conversazione.

Genera token

Genera un token valido per una conversazione.

POST /v3/directline/tokens/generate

Aggiorna token

Aggiorna il token.

POST /v3/directline/tokens/refresh

Operazioni di conversazione

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

Avvia la conversazione

Apre una nuova conversazione con il bot.

POST /v3/directline/conversations

Ottenere informazioni sulla conversazione

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

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

Ottenere attività

Recupera le attività dal bot per la conversazione specificata. Facoltativamente, è possibile specificare il watermark parametro 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 userId parametro 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 Direct Line 3.0 include tutti gli oggetti definiti dallo schema di Bot Framework, nonché alcuni oggetti specifici per 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.

Activities

Per ogni attività ricevuta da un client da un bot tramite Direct Line:

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

I client possono ricevere più attività dal bot come parte di un ActivitySet.

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

• La type proprietà specifica l'attività di tipo che invia (in genere il messaggio).
• La from proprietà deve essere popolata con un ID utente, scelto dal client.
• Gli allegati possono contenere URL a risorse o URL esistenti caricati tramite l'endpoint dell'allegato Direct Line.
• La channelData proprietà viene mantenuta senza modifiche.
• Le dimensioni totali dell'attività, se serializzate in JSON e crittografate, 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 una singola attività per ogni richiesta.

Risorse aggiuntive

• Specifica del protocollo di attività