Partilhar via

Referência da API - Direct Line API 3.0

  • Artigo

Você pode habilitar seu aplicativo cliente para se comunicar com seu bot usando a API de Linha Direta 3.0. A API de Linha Direta 3.0 usa REST e JSON padrão do setor sobre HTTPS.

URI Base

Para acessar a API de Linha Direta 3.0, use um destes URIs básicos para todas as solicitações de API:

  • Para bots globais, use https://directline.botframework.com

  • Para um bot regional, insira o seguinte uri de acordo com a região selecionada:

    País/Região URI Base
    Europa https://europe.directline.botframework.com
    Índia https://india.directline.botframework.com

Gorjeta

Uma solicitação pode falhar se você usar o URI de base global para um bot regional, pois algumas solicitações podem ir além dos limites geográficos.

Cabeçalhos

Além dos cabeçalhos de solicitação HTTP padrão, uma solicitação de API de Linha Direta deve incluir um Authorization cabeçalho que especifique um segredo ou token para autenticar o cliente que está emitindo a solicitação. Especifique o Authorization cabeçalho usando este formato:

Authorization: Bearer SECRET_OR_TOKEN

Para obter detalhes sobre como obter um segredo ou token que seu cliente pode usar para autenticar suas solicitações de API de Linha Direta, consulte Autenticação.

Códigos de estado HTTP

O código de status HTTP retornado com cada resposta indica o resultado da solicitação correspondente.

Código de estado HTTP Significado
200 O pedido foi bem-sucedido.
201 O pedido foi bem-sucedido.
202 O pedido foi aceite para processamento.
204 O pedido foi bem-sucedido, mas nenhum conteúdo foi devolvido.
400 O pedido estava mal formado ou incorreto.
401 O cliente não está autorizado a fazer o pedido. Muitas vezes, esse código de status ocorre porque o Authorization cabeçalho está ausente ou malformado.
403 O cliente não tem permissão para executar a operação solicitada. A operação pode falhar pelos seguintes motivos.
  • Um token inválido: quando a solicitação usa um token que era válido anteriormente, mas expirou, a code propriedade Error que é retornada dentro do objeto ErrorResponse é definida como .TokenExpired
  • Uma violação de limite de dados: se o bot for um bot regional, mas o URI de base não for regional, algumas solicitações podem ir além dos limites geográficos.
  • Um recurso de destino inválido: o bot ou site de destino é inválido ou foi excluído.
404 O recurso solicitado não foi encontrado. Normalmente, esse código de status indica um URI de solicitação inválido.
500 Ocorreu um erro interno do servidor no serviço Direct Line.
502 O bot não está disponível ou retornou um erro. Este é um código de erro comum.

Nota

O código de status HTTP 101 é usado no caminho de conexão WebSocket, embora isso provavelmente seja tratado pelo seu cliente WebSocket.

Erros

Qualquer resposta que especifique um código de status HTTP no intervalo 4xx ou 5xx incluirá um objeto ErrorResponse no corpo da resposta que fornece informações sobre o erro. Se você receber uma resposta de erro no intervalo 4xx, inspecione o objeto ErrorResponse para identificar a causa do erro e resolver o problema antes de reenviar a solicitação.

Nota

Os códigos de status HTTP e os code valores especificados na propriedade dentro do objeto ErrorResponse são estáveis. Os valores especificados na message propriedade dentro do objeto ErrorResponse podem mudar ao longo do tempo.

Os trechos a seguir mostram uma solicitação de exemplo e a resposta de erro resultante.

Pedir

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"
    }
}

Operações de token

Use essas operações para criar ou atualizar um token que um cliente pode usar para acessar uma única conversa.

Operation Description
Gerar Token Gere um token para uma nova conversa.
Atualizar token Atualize um token.

Gerar Token

Gera um token válido para uma conversa.

POST /v3/directline/tokens/generate
Conteúdo Description
Corpo do pedido Um objeto TokenParameters
Devoluções Um objeto Conversation

Atualizar token

Atualiza o token.

POST /v3/directline/tokens/refresh
Conteúdo Description
Corpo do pedido n/d
Devoluções Um objeto Conversation

Operações de conversação

Use essas operações para abrir uma conversa com seu bot e trocar atividades entre cliente e bot.

Operation Description
Iniciar conversa Abre uma nova conversa com o bot.
Obter informações de conversação Obtém informações sobre uma conversa existente. Essa operação gera uma nova URL de fluxo WebSocket que um cliente pode usar para se reconectar a uma conversa.
Obter atividades Recupera atividades do bot.
Enviar uma atividade Envia uma atividade para o bot.
Carregar e enviar ficheiro(s) Carrega e envia ficheiro(s) como anexo(s).

Iniciar conversa

Abre uma nova conversa com o bot.

POST /v3/directline/conversations
Conteúdo Description
Corpo do pedido Um objeto TokenParameters
Devoluções Um objeto Conversation

Obter informações de conversação

Obtém informações sobre uma conversa existente e também gera uma nova URL de fluxo WebSocket que um cliente pode usar para se reconectar a uma conversa. Opcionalmente, você pode fornecer o watermark parâmetro no URI de solicitação para indicar a mensagem mais recente vista pelo cliente.

GET /v3/directline/conversations/{conversationId}?watermark={watermark_value}
Conteúdo Description
Corpo do pedido n/d
Devoluções Um objeto Conversation

Obter atividades

Recupera atividades do bot para a conversa especificada. Opcionalmente, você pode fornecer o watermark parâmetro no URI de solicitação para indicar a mensagem mais recente vista pelo cliente.

GET /v3/directline/conversations/{conversationId}/activities?watermark={watermark_value}
Conteúdo Description
Corpo do pedido n/d
Devoluções Um objeto ActivitySet . A resposta contém watermark como uma propriedade do ActivitySet objeto. Os clientes devem percorrer as atividades disponíveis, adiantando o watermark valor até que nenhuma atividade seja retornada.

Enviar uma atividade

Envia uma atividade para o bot.

POST /v3/directline/conversations/{conversationId}/activities
Conteúdo Description
Corpo do pedido Um objeto Activity
Devoluções Um ResourceResponse que contém uma id propriedade que especifica a ID da atividade que foi enviada para o bot.

Carregar e enviar ficheiro(s)

Carrega e envia ficheiro(s) como anexo(s). Defina o userId parâmetro no URI de solicitação para especificar a ID do usuário que está enviando o(s) anexo(s).

POST /v3/directline/conversations/{conversationId}/upload?userId={userId}
Conteúdo Description
Corpo do pedido Para um único anexo, preencha o corpo da solicitação com o conteúdo do arquivo. Para vários anexos, crie um corpo de solicitação de várias partes que contenha uma parte para cada anexo e também (opcionalmente) uma parte para o objeto Activity que deve servir como contêiner para o(s) anexo(s) especificado(s). Para obter mais informações, consulte Enviar uma atividade para o bot.
Devoluções Um ResourceResponse que contém uma id propriedade que especifica a ID da atividade que foi enviada para o bot.

Nota

Os ficheiros carregados são eliminados após 24 horas.

Esquema

O esquema da Linha Direta 3.0 inclui todos os objetos definidos pelo esquema do Bot Framework, bem como alguns objetos específicos da Linha Direta.

Objeto ActivitySet

Define um conjunto de atividades.

Propriedade Type Description
Atividades Atividade[] Matriz de objetos Activity.
marca d'água string Marca d'água máxima de atividades dentro do conjunto. Um cliente pode usar o watermark valor para indicar a mensagem mais recente que viu ao recuperar atividades do bot ou ao gerar uma nova URL de fluxo WebSocket.

Objeto de conversação

Define uma conversa de Linha Direta.

Propriedade Type Description
conversaId string ID que identifica exclusivamente a conversa para a qual o token especificado é válido.
eTag string Um HTTP ETag (marca de entidade).
expires_in Número Número de segundos até o token expirar.
referenceGrammarId string ID para a gramática de referência para este bot.
streamUrl string URL do fluxo de mensagens da conversa.
ficha string Token válido para a conversa especificada.

Objeto TokenParameters

Parâmetros para criar um token.

Propriedade Type Description
eTag string Um HTTP ETag (marca de entidade).
trustedOrigins string[] Origens confiáveis para incorporar no token.
Utilizador ChannelAccount Conta de usuário para incorporar no token.

Atividades

Para cada atividade que um cliente recebe de um bot via Direct Line:

  • Os cartões anexos são preservados.
  • Os URLs dos anexos carregados ficam ocultos com um link privado.
  • O channelData imóvel é preservado sem modificações.

Os clientes podem receber várias atividades do bot como parte de um ActivitySet.

Quando um cliente envia um Activity para um bot via Linha Direta:

  • A type propriedade especifica a atividade de tipo que está enviando (normalmente mensagem).
  • A from propriedade deve ser preenchida com um ID de usuário, escolhido pelo cliente.
  • Os anexos podem conter URLs para recursos existentes ou URLs carregadas através do ponto de extremidade de anexo de Linha Direta.
  • O channelData imóvel é preservado sem modificações.
  • O tamanho total da atividade, quando serializada para JSON e criptografada, não deve exceder 256K caracteres. Recomendamos que mantenha atividades abaixo de 150K. Se forem necessários mais dados, considere dividir a atividade ou usar anexos.

Os clientes podem enviar uma única atividade por solicitação.

Recursos adicionais