Nota
O acesso a esta página requer autorização. Pode tentar iniciar sessão ou alterar os diretórios.
O acesso a esta página requer autorização. Pode tentar alterar os diretórios.
Os agentes podem receber, ler e enviar documentos em conversas do Microsoft Teams. O Teams armazena esses arquivos no OneDrive ou no SharePoint e os exibe como cartões de arquivo ou itens armazenados.
Use o SDK do Teams para receber arquivos em chats pessoais e enviar arquivos por meio do consentimento de arquivos do bot. Use o Microsoft Graph quando seu agente precisar trabalhar com arquivos armazenados em chats pessoais, chats em grupo e canais. Para imagens que são renderizadas diretamente em uma conversa, consulte Enviar e receber imagens embutidas.
Importante
Os agentes não dão suporte a fluxos de trabalho de envio e recebimento de arquivos de documentos na Nuvem da Comunidade Governamental Alta (GCC High), no DoD (Departamento de Defesa) ou no Teams operado pela 21Vianet.
Experiência do usuário
Entenda como os usuários trocam documentos com um agente para que você possa fornecer prompts claros, solicitações de consentimento e confirmações. Os usuários podem:
- Anexe um documento a um chat pessoal com um agente.
- Revise e aceite ou recuse um arquivo oferecido por um agente.
- Abra um arquivo carregado com êxito a partir de seu card de arquivos.
- Trabalhe com arquivos armazenados do OneDrive ou do SharePoint em todos os escopos de conversa com suporte.
Um documento recebido é armazenado no OneDrive ou no SharePoint e aparece como um arquivo, um card ou um item armazenado. Um bot que envia um arquivo no chat pessoal primeiro pede consentimento, carrega o arquivo após a aceitação e, em seguida, envia um card de informações do arquivo.
Experiência do desenvolvedor
Escolha uma API de arquivo com base na identidade do aplicativo, na direção e no escopo da conversa. As opções a seguir correspondem à ordem de implementação neste artigo:
| Requisito | Abordagem recomendada |
|---|---|
| Receber e ler um documento em um chat pessoal | Acessador de arquivo SDK do Teams |
| Enviar ou recuperar arquivos armazenados em vários escopos de conversa | Microsoft Graph |
| Enviar um documento de um bot em um chat pessoal | Consentimento do arquivo SDK do Teams |
O acessador de arquivo do SDK do Teams filtra a coleção de anexos da atividade e expõe documentos compatíveis como identificadores lentos de arquivos de entrada. Os usuários agenciais recuperam bytes de arquivo por meio do Microsoft Graph com suas identidades. Os bots tradicionais usam a URL pré-autorizada e de curta duração fornecida pelo Teams.
| Operação | Chat pessoal | Chat em grupo | Canal | Requisito |
|---|---|---|---|---|
| Receber arquivos com o acessador de arquivo do SDK do Teams | Com suporte | Não há suporte explícito | Não há suporte explícito | Os usuários do Agentic exigem permissões de arquivo do Graph. Os bots usam uma URL pré-autorizada. |
| Enviar ou recuperar arquivos com o Graph | Com suporte | Com suporte | Com suporte | Configure permissões para o local de armazenamento, a API, a identidade de chamada e o modelo de acesso. |
| Enviar arquivos com consentimento de arquivo de bot | Com suporte | Sem suporte | Sem suporte | Defina supportsFiles como true na entrada do bot. |
Receber arquivos
Receba arquivos de documentos que os usuários anexam a chats pessoais para que seu agente possa inspecionar ou processar seu conteúdo. Configure o acesso ao arquivo primeiro e, em seguida, use o acessador de arquivo SDK do Teams para listar e ler cada arquivo recebido.
Configurar suporte a arquivo
Configure o suporte a arquivos para que seu agente ou bot tenha as permissões e as configurações de plataforma necessárias para receber documentos. Conclua a configuração da identidade do aplicativo antes de implementar manipuladores de arquivos.
A configuração necessária depende da identidade e da operação de arquivo:
| Cenário | Atualização do manifesto do aplicativo | Outras configurações |
|---|---|---|
| O usuário agêntico recebe um arquivo | Nenhum | Adicione uma permissão de arquivo do Microsoft Graph ao blueprint do agente e obtenha o consentimento do administrador. |
| O bot recebe ou envia um arquivo por meio do consentimento do arquivo | Defina supportsFiles como true na entrada do bot. |
Nenhum para a URL do arquivo pré-autorizada fornecida pelo Teams. |
| O aplicativo envia ou recupera um arquivo armazenado com o Microsoft Graph | Nenhuma propriedade de manifesto de aplicativo específica do arquivo | Configure a permissão e a autenticação necessárias do Microsoft Graph para a identidade de chamada. |
Usuário agencial
Para um usuário agenci, você não precisa definir supportsFiles ou adicionar outra propriedade de manifesto de aplicativo específica do arquivo. Configure uma permissão de arquivo do Microsoft Graph no blueprint do agente e obtenha o consentimento do administrador. O usuário agenciável recupera o conteúdo do arquivo por meio do Microsoft Graph com sua própria identidade. Para obter mais informações, consulte permissões herdáveis.
Importante
Configure e dê consentimento à permissão de blueprint antes de testar a recuperação de arquivo. Sem uma credencial do Graph, o SDK gera um erro de credencial de arquivo.
Bot
Para um bot que recebe arquivos ou usa consentimento de arquivo, defina supportsFiles como true na entrada do bot do manifesto do aplicativo:
{
"bots": [
{
"botId": "${{BOT_ID}}",
"scopes": ["personal"],
"supportsFiles": true
}
]
}
Valores da chave:
-
botId: Defina${{BOT_ID}}para identificar o registro do seu bot. -
scopes: adicionepersonalpara habilitar interações de arquivo um-para-um. -
supportsFiles: definidatruepara expor o controle de anexo de arquivo.
Sem supportsFiles: true, os usuários não podem anexar arquivos em um chat pessoal com o bot e o acessador de arquivo retorna uma coleção vazia. Essa configuração não concede permissões ao Microsoft Graph.
Acessar arquivos e metadados recebidos
Quando um usuário anexa um documento em um chat pessoal, o Teams o armazena no OneDrive ou no SharePoint. A atividade de mensagem contém metadados de arquivo e o acessador de arquivo SDK do Teams fornece acesso lento aos bytes do arquivo.
Use ListAsync() para acessar todos os arquivos com suporte anexados à mensagem atual:
teamsApp.OnMessage(async (context, cancellationToken) =>
{
IList<IncomingFile> files =
await context.Files.ListAsync(cancellationToken);
if (files.Count == 0)
{
await context.ReplyAsync(
"Attach a file and I will read it.",
cancellationToken);
return;
}
string names = string.Join(", ", files.Select(file => file.Name));
await context.ReplyAsync(
$"You sent {files.Count} file(s): {names}",
cancellationToken);
});
Principais APIs e valores:
-
context.Files.ListAsync: retorna metadados de arquivo sem baixar bytes de arquivo. -
file.Name: leia o nome fornecido pelo carregador apenas para exibição.
ListAsync() Preserva a ordem dos anexos. Ele retorna uma coleção vazia para atividades sem arquivos compatíveis e ignora entradas de arquivo malformadas. Use FirstAsync() quando o manipulador espera um arquivo:
IncomingFile? file =
await context.Files.FirstAsync(cancellationToken);
if (file is not null)
{
await context.ReplyAsync(
$"Reading {file.Name}...",
cancellationToken);
}
Principais APIs e valores:
-
FirstAsync: retorna o primeiro arquivo com suporte ounull. -
file.Name: exiba o nome fornecido pelo carregador do arquivo recebido.
Use list() para acessar todos os arquivos com suporte anexados à mensagem atual:
app.on('message', async ({ files, send }) => {
const attached = await files.list();
if (attached.length === 0) {
await send('Attach a file and I will read it.');
return;
}
const names = attached.map((file) => file.name).join(', ');
await send(`You sent ${attached.length} file(s): ${names}`);
});
Principais APIs e valores:
-
files.list: retorna metadados de arquivo sem baixar bytes de arquivo. -
file.name: leia o nome fornecido pelo carregador apenas para exibição.
list() Preserva a ordem dos anexos. Ele retorna uma matriz vazia para atividades sem arquivos suportados e pula entradas de arquivo malformadas. Use first() quando o manipulador espera um arquivo:
const file = await files.first();
if (file) {
await send(`Reading ${file.name}...`);
}
Principais APIs e valores:
-
first: retorna o primeiro arquivo com suporte ouundefined. -
file.name: exiba o nome fornecido pelo carregador do arquivo recebido.
Use list() para acessar todos os arquivos com suporte anexados à mensagem atual:
@app.on_message
async def handle_message(ctx: ActivityContext[MessageActivity]) -> None:
attached = await ctx.files.list()
if not attached:
await ctx.reply("Attach a file and I will read it.")
return
names = ", ".join(file.name for file in attached)
await ctx.reply(f"You sent {len(attached)} file(s): {names}")
Principais APIs e valores:
-
ctx.files.list: retorna metadados de arquivo sem baixar bytes de arquivo. -
file.name: leia o nome fornecido pelo carregador apenas para exibição.
list() Preserva a ordem dos anexos. Ele retorna uma lista vazia para atividades sem arquivos compatíveis e ignora entradas de arquivo malformadas. Use first() quando o manipulador espera um arquivo:
file = await ctx.files.first()
if file:
await ctx.reply(f"Reading {file.name}...")
Principais APIs e valores:
-
first: retorna o primeiro arquivo com suporte ouNone. -
file.name: exiba o nome fornecido pelo carregador do arquivo recebido.
Um identificador de arquivo de entrada inclui:
- ID exclusiva: ID do item de unidade do OneDrive ou do SharePoint, quando disponível.
- Nome: nome de arquivo fornecido pelo carregador, incluindo sua extensão de arquivo.
- Extensão: extensão fornecida pela plataforma sem o período inicial.
- Tipo de conteúdo: tipo MIME quando fornecido pela fonte.
- Escopo: Escopo da conversa em que o arquivo foi recebido.
- Origem: origem do SDK que identificou o arquivo de entrada.
- URL do conteúdo: URL de armazenamento navegável, não necessariamente uma URL de download.
- Anexo bruto: Metadados originais para diagnóstico no nível do protocolo.
Cuidado
Tratar Name como entrada não confiável. Antes de gravar um arquivo, substitua-o por um nome seguro gerado pelo aplicativo ou limpe-o e verifique se o destino resolvido permanece dentro de um diretório controlado pelo aplicativo.
Ler um arquivo recebido
Leia um arquivo recebido quando seu aplicativo precisar de seu conteúdo de texto ou binário para processamento, armazenamento ou análise. Use o método de download para uma cópia reutilizável na memória ou selecione um método de streaming para arquivos grandes.
Use DownloadAsync() para baixar um arquivo em uma cópia reutilizável na memória:
IncomingFile? file =
await context.Files.FirstAsync(cancellationToken);
if (file is not null)
{
DownloadedFile downloaded =
await file.DownloadAsync(cancellationToken);
await context.ReplyAsync(
$"Downloaded {downloaded.Filename} " +
$"({downloaded.Bytes.Length} bytes, {downloaded.ContentType}).",
cancellationToken);
}
Principais APIs e valores:
-
DownloadAsync: Busca e armazena em buffer uma cópia reutilizável de bytes. -
downloaded.Bytes: Acesse o conteúdo binário completo do arquivo baixado. -
downloaded.ContentType: use o tipo MIME resolvido para processamento. -
downloaded.Filename: Use o nome resolvido para fins de exibição.
Outras opções de leitura incluem:
-
TextAsync(): Baixe e decodifique texto como UTF-8 por padrão. -
StreamAsync(): processe arquivos grandes sem armazená-los completamente em buffer. -
SaveAsAsync(path): Stream bytes diretamente para um caminho local seguro.
TextAsync() Substitui sequências de bytes inválidas por U+FFFD. Forneça um Encoding para texto não UTF-8 e processe arquivos binários como bytes ou fluxos.
Não IncomingFile armazena bytes em cache. Toda chamada para DownloadAsync(), TextAsync(), StreamAsync()ou SaveAsAsync() executa outra solicitação de rede. Baixe uma vez e reutilize DownloadedFile quando precisar do mesmo conteúdo mais de uma vez:
DownloadedFile downloaded =
await file.DownloadAsync(cancellationToken);
string text = downloaded.Text();
byte[] bytes = downloaded.Bytes;
await downloaded.SaveAsAsync(
"./downloads/copy.bin",
cancellationToken);
Principais APIs e valores:
-
downloaded.Text(): Decodifique a cópia em buffer sem outro download. -
downloaded.Bytes: Reutilize bytes armazenados em buffer para processamento binário. -
SaveAsAsync: Salve bytes armazenados em buffer sem buscar o arquivo novamente.
Use download() para baixar um arquivo em uma cópia reutilizável na memória:
const file = await files.first();
if (file) {
const downloaded = await file.download();
await send(
`Downloaded ${downloaded.filename} ` +
`(${downloaded.bytes.length} bytes, ${downloaded.contentType}).`
);
}
Principais APIs e valores:
-
download: Busca e armazena em buffer uma cópia reutilizável de bytes. -
downloaded.bytes: Acesse o conteúdo binário do arquivo baixado. -
downloaded.contentType: use o tipo MIME resolvido para processamento. -
downloaded.filename: Use o nome resolvido para fins de exibição.
Outras opções de leitura incluem:
-
text(): Baixe e decodifique texto como UTF-8 por padrão. -
stream(): processe arquivos grandes sem armazená-los completamente em buffer. -
saveAs(path): Stream bytes diretamente para um caminho local seguro.
Um arquivo de entrada não armazena bytes em cache. Baixe uma vez e reutilize o arquivo baixado quando precisar do mesmo conteúdo mais de uma vez:
const downloaded = await file.download();
const text = downloaded.text();
const buffer = downloaded.arrayBuffer();
await downloaded.saveAs('./downloads/copy.bin');
Principais APIs e valores:
-
downloaded.text(): Decodifique a cópia em buffer sem outro download. -
downloaded.arrayBuffer(): Reutilize bytes armazenados em buffer para processamento binário. -
saveAs: Salve bytes armazenados em buffer sem buscar o arquivo novamente.
Use download() para baixar um arquivo em uma cópia reutilizável na memória:
file = await ctx.files.first()
if file:
downloaded = await file.download()
await ctx.reply(
f"Downloaded {downloaded.filename} "
f"({len(downloaded.bytes)} bytes, {downloaded.content_type})."
)
Principais APIs e valores:
-
download: Busca e armazena em buffer uma cópia reutilizável de bytes. -
downloaded.bytes: Acesse o conteúdo binário do arquivo baixado. -
downloaded.content_type: use o tipo MIME resolvido para processamento. -
downloaded.filename: Use o nome resolvido para fins de exibição.
Outras opções de leitura incluem:
-
text(): Baixe e decodifique texto como UTF-8 por padrão. -
stream(): processe arquivos grandes sem armazená-los completamente em buffer. -
save_as(path): Stream bytes diretamente para um caminho local seguro.
Um arquivo de entrada não armazena bytes em cache. Baixe uma vez e reutilize o arquivo baixado quando precisar do mesmo conteúdo mais de uma vez:
downloaded = await file.download()
text = downloaded.text()
data = downloaded.bytes
await downloaded.save_as("./downloads/copy.bin")
Principais APIs e valores:
-
downloaded.text(): Decodifique a cópia em buffer sem outro download. -
downloaded.bytes: Reutilize bytes armazenados em buffer para processamento binário. -
save_as: Salve bytes armazenados em buffer sem buscar o arquivo novamente.
Para um usuário agente, o SDK do Teams usa o anexo ContentUrl e a identidade do usuário agencial para recuperar o arquivo por meio do Microsoft Graph. Para um bot, o SDK usa o pré-autorizado downloadUrl de curta duração fornecido na atividade. As APIs de leitura de arquivo mostradas nesta seção se aplicam a ambas as rotas.
Acessar o anexo do arquivo bruto
Acesse o anexo bruto quando precisar de metadados de protocolo que o acessador de arquivo digitado não expõe, como para diagnóstico ou solução de problemas. Inspecione a carga bruta somente quando necessário e registre apenas campos não confidenciais e explicitamente selecionados.
Use IncomingFile.Raw somente quando precisar do conteúdo do protocolo original. O exemplo a seguir registra o nome do anexo e o tipo de conteúdo em vez de serializar o objeto completo:
IncomingFile? file =
await context.Files.FirstAsync(cancellationToken);
if (file is not null)
{
logger.LogDebug(
"File attachment received. Name: {Name}; Content type: {ContentType}",
file.Raw.Name,
file.Raw.ContentType);
}
Principais APIs e valores:
-
file.Raw: acesse os metadados originais para diagnóstico ou solução de problemas. -
file.Raw.Name: registre o nome de exibição somente depois de validar sua confidencialidade. -
file.Raw.ContentType: registre o tipo de anexo sem expor suas URLs. -
logger.LogDebug: registre os metadados selecionados em vez do conteúdo completo.
Use IIncomingFile.raw somente quando precisar do conteúdo do protocolo original. O exemplo a seguir registra o nome do anexo e o tipo de conteúdo em vez do objeto completo:
const file = await files.first();
if (file) {
log.debug('File attachment received', {
name: file.raw.name,
contentType: file.raw.contentType
});
}
Principais APIs e valores:
-
file.raw: acesse os metadados originais para diagnóstico ou solução de problemas. -
file.raw.name: registre o nome de exibição somente depois de validar sua confidencialidade. -
file.raw.contentType: registre o tipo de anexo sem expor suas URLs. -
log.debug: registre os metadados selecionados em vez do conteúdo completo.
Use IncomingFile.raw somente quando precisar do conteúdo do protocolo original. O exemplo a seguir registra o nome do anexo e o tipo de conteúdo em vez do objeto completo:
file = await ctx.files.first()
if file:
ctx.logger.debug(
"File attachment received. Name: %s; Content type: %s",
file.raw.name,
file.raw.content_type,
)
Principais APIs e valores:
-
file.raw: acesse os metadados originais para diagnóstico ou solução de problemas. -
file.raw.name: registre o nome de exibição somente depois de validar sua confidencialidade. -
file.raw.content_type: registre o tipo de anexo sem expor suas URLs. -
ctx.logger.debug: registre os metadados selecionados em vez do conteúdo completo.
Não registre URLs de anexos brutos, identificadores ou o conteúdo completo. O acessador de arquivo não retorna imagens embutidas, cartões, menções, visualizações de links, anexos HTML ou entradas de arquivo malformadas. Acesse esses itens por meio da coleção de anexos da atividade. Para obter orientações específicas da imagem, consulte Enviar e receber imagens embutidas.
Enviar arquivos
Envie documentos armazenados aos usuários quando seu aplicativo precisar entregar relatórios gerados, exportações ou outro conteúdo para baixar. Use o Microsoft Graph para cenários agenciais e de escopo cruzado ou use o consentimento de arquivo de bot em chats pessoais.
Usar o Microsoft Graph para arquivos armazenados
Use o Microsoft Graph quando seu aplicativo precisar enviar ou recuperar arquivos armazenados em chats pessoais, chats em grupo ou canais:
- Use o OneDrive de um usuário para arquivos pessoais e de chat em grupo.
- Use o site do SharePoint da equipe para arquivos de canal.
- Obtenha o acesso de armazenamento necessário por meio do OAuth 2.0.
- Poste um anexo de mensagem que faça referência a um arquivo armazenado existente.
Para obter mais informações, consulte enviar anexos de arquivo de mensagem de chat e APIs do OneDrive e do SharePoint.
Enviar arquivos com consentimento de arquivo de bot
Use o fluxo de trabalho de consentimento de arquivo do bot para solicitar permissão antes que o bot carregue um documento no OneDrive de um usuário. Implemente a seguinte sequência para chats pessoais:
- Enviar um
FileConsentCardarquivo . - Receber uma
fileConsent/invokeatividade. - Se o usuário aceitar, carregue os bytes no
uploadUrlcom HTTPPUT. - Envie um
FileInfoCardlink para o arquivo carregado. - Se o usuário recusar, descarte o conteúdo pendente.
Solicitar consentimento de arquivo
Solicite consentimento para que o usuário possa revisar o nome, a finalidade e o tamanho do arquivo antes que seu aplicativo o carregue no OneDrive. Envie um FileConsentCard e retenha o conteúdo do arquivo pendente até que o usuário aceite ou recuse.
A mensagem a seguir solicita permissão para carregar um arquivo:
No celular, a solicitação de consentimento aparece da seguinte forma:
{
"attachments": [
{
"contentType": "application/vnd.microsoft.teams.card.file.consent",
"name": "file_example.txt",
"content": {
"description": "This is your monthly expense report.",
"sizeInBytes": 1029393,
"acceptContext": {
"fileId": "expense-report-2026-09"
},
"declineContext": {
"fileId": "expense-report-2026-09"
}
}
}
]
}
Propriedades e valores chave:
-
contentType: Use o tipo de conteúdo do card de consentimento de arquivo mostrado. -
name: Defina o nome do arquivo que o Teams exibe para os usuários. -
description: Adicione uma breve finalidade para o arquivo oferecido. -
sizeInBytes: defina o tamanho exato do arquivo em bytes. -
acceptContext: adicione identificadores necessários após o usuário aceitar. -
declineContext: adicione os identificadores necessários após o usuário recusar.
Manter os bytes do arquivo pendente fora do objeto de contexto. Aplique políticas de expiração e limpeza a uploads pendentes.
Lidar com aceitação ou recusa
Manipule a resposta de consentimento para decidir se deseja carregar o arquivo pendente ou descartá-lo. Inspecione a fileConsent/invoke ação e retenha apenas os identificadores necessários para localizar o conteúdo pendente.
Quando o usuário aceita, o Teams envia fileConsent/invoke com definido para actionaccept e um uploadInfo.uploadUrl. Se o usuário recusar, action é decline.
Carregar conteúdo do arquivo
Carregue os bytes pendentes somente depois que o usuário aceitar o arquivo. Use a URL de upload fornecida, os cabeçalhos de intervalo de bytes necessários e o HTTP PUTe, em seguida, verifique se o OneDrive retorna um status bem-sucedido.
Use a URL de upload para transferir os bytes do arquivo:
using System.Net;
using System.Net.Http.Headers;
async Task UploadToOneDrive(
string url,
byte[] content,
CancellationToken cancellationToken)
{
if (content.Length == 0)
{
throw new ArgumentException(
"The file content must not be empty.",
nameof(content));
}
using var request = new HttpRequestMessage(HttpMethod.Put, url);
request.Content = new ByteArrayContent(content);
request.Content.Headers.ContentType =
new MediaTypeHeaderValue("application/octet-stream");
request.Content.Headers.ContentLength = content.Length;
request.Content.Headers.ContentRange =
new ContentRangeHeaderValue(0, content.Length - 1, content.Length);
using HttpResponseMessage response =
await httpClient.SendAsync(request, cancellationToken);
if (response.StatusCode is not HttpStatusCode.OK
and not HttpStatusCode.Created)
{
throw new HttpRequestException(
$"Upload failed with status {response.StatusCode}.");
}
}
Parâmetros e valores chave:
-
url: Use o retornado após aUploadInfo.UploadUrlaceitação. -
content: forneça os bytes exatos associados ao consentimento. -
content.Length: rejeite um upload vazio antes de criar seu intervalo de bytes. -
ContentType: Definaapplication/octet-streampara transferência binária. -
ContentLength: defina o número exato de bytes carregados. -
ContentRange: Descreva o intervalo de bytes e o total carregados. -
httpClient.SendAsync: envie a solicitação HTTPPUTpara o OneDrive. -
response.StatusCode: aceite o HTTP 200 ou 201 e, caso contrário, falhará.
import axios from 'axios';
async function uploadToOneDrive(url: string, content: Buffer): Promise<void> {
if (content.length === 0) {
throw new Error('The file content must not be empty.');
}
const fileSize = content.length;
const response = await axios.put(url, content, {
headers: {
'Content-Type': 'application/octet-stream',
'Content-Length': fileSize.toString(),
'Content-Range': `bytes 0-${fileSize - 1}/${fileSize}`
}
});
if (![200, 201].includes(response.status)) {
throw new Error(`Upload failed with status ${response.status}`);
}
}
Parâmetros e valores chave:
-
url: Use o retornado após auploadInfo.uploadUrlaceitação. -
content: forneça os bytes exatos associados ao consentimento. -
content.length: rejeite um upload vazio antes de criar seu intervalo de bytes. -
Content-Type: Definaapplication/octet-streampara transferência de arquivos binários. -
Content-Length: defina o comprimento decimal dos bytes carregados. -
Content-Range: Descreva o intervalo de bytes e o total carregados. -
axios.put: carregue os bytes com uma solicitação HTTPPUT. -
response.status: aceite o HTTP 200 ou 201 e falhe em outras respostas.
import httpx
async def upload_to_onedrive(url: str, content: bytes) -> None:
if not content:
raise ValueError("The file content must not be empty.")
file_size = len(content)
headers = {
"Content-Type": "application/octet-stream",
"Content-Length": str(file_size),
"Content-Range": f"bytes 0-{file_size - 1}/{file_size}",
}
async with httpx.AsyncClient() as client:
response = await client.put(url, content=content, headers=headers)
if response.status_code not in (200, 201):
raise RuntimeError(
f"Upload failed with status {response.status_code}"
)
Parâmetros e valores chave:
-
url: Use o retornado após aupload_info.upload_urlaceitação. -
content: forneça os bytes exatos associados ao consentimento. -
if not content: rejeite um upload vazio antes de criar seu intervalo de bytes. -
Content-Type: Definaapplication/octet-streampara transferência binária. -
Content-Length: defina o número exato de bytes carregados. -
Content-Range: Descreva o intervalo de bytes e o total carregados. -
httpx.AsyncClient.put: carregue os bytes com uma solicitação HTTPPUT. -
response.status_code: aceite o HTTP 200 ou 201 e, caso contrário, falhará.
Notificar o usuário
Notifique o usuário após o upload ser bem-sucedido para que ele possa abrir ou baixar o arquivo armazenado. Envie um FileInfoCard contendo o identificador de item de unidade, o tipo de arquivo e a URL do arquivo armazenado.
Após um upload bem-sucedido, envie um anexo de informações de arquivo:
{
"attachments": [
{
"contentType": "application/vnd.microsoft.teams.card.file.info",
"contentUrl": "https://contoso.sharepoint.com/personal/user/Documents/Applications/file_example.txt",
"name": "file_example.txt",
"content": {
"uniqueId": "1150D938-8870-4044-9F2C-5BBDEBA70C8C",
"fileType": "txt"
}
}
]
}
Propriedades e valores chave:
-
contentType: Use o tipo de conteúdo de card de informações de arquivo mostrado. -
contentUrl: defina a URL do arquivo armazenado para acesso do usuário. -
uniqueId: defina a ID do item de unidade do OneDrive ou do SharePoint. -
fileType: Defina a extensão de arquivo relatada pela plataforma sem pontuação.
Lidar com erros
Manipule erros de arquivo SDK conhecidos separadamente de falhas de transporte e serviço. Para usuários agenciados, lide primeiro com erros de acesso a credenciais e ao Graph porque a recuperação de arquivo depende da identidade do agente e das permissões de blueprint consentidas. O erro de URL expirada se aplica ao caminho do bot que usa uma URL de download pré-autorizada.
| Código de status | Código de erro | Descrição | Ação do desenvolvedor |
|---|---|---|---|
| Não aplicável | FileCredentialException |
Nenhuma credencial do Graph está disponível para recuperação de arquivo de usuário agente. | Verifique as permissões do blueprint, o consentimento do administrador e a configuração de credenciais. |
| HTTP 401 | FileAccessException |
O Microsoft Graph rejeitou o token usado para recuperar o arquivo. | Atualize ou corrija o token e verifique o ator selecionado. |
| HTTP 403 | FileAccessException |
A identidade não tem consentimento ou acesso ao item solicitado. | Verifique o consentimento, o compartilhamento, as permissões de blueprint e o acesso ao item. |
| Não aplicável | FileUrlExpiredException |
A URL do arquivo pré-autorizado do bot expirou antes da recuperação ou releitura. | Peça ao usuário para anexar o arquivo novamente. Baixar uma vez e reutilizar DownloadedFile. |
| Não aplicável | FileScopeNotSupportedException |
A API de arquivo de alto nível recebeu um escopo de conversa sem suporte. | Use o chat pessoal ou recupere o arquivo armazenado por meio do Microsoft Graph. |
| Não aplicável | FileException |
Uma operação de arquivo SDK conhecida falhou por outro motivo. | Mostrar uma mensagem geral do usuário e registrar o diagnóstico limpo. |
| HTTP 5xx | Erro de transporte ou serviço | O Microsoft Graph ou o serviço de armazenamento não pôde concluir a solicitação. | Tente novamente de acordo com as diretrizes de serviço e preserve a exceção original. |
Um 403 pode representar consentimento ausente, acesso a um item ausente ou um item inexistente. O SDK não expõe um erro de arquivo não encontrado separado para essas respostas.
try
{
DownloadedFile downloaded =
await file.DownloadAsync(cancellationToken);
}
catch (FileCredentialException)
{
await context.ReplyAsync(
"The agent isn't configured to access this file.",
cancellationToken);
}
catch (FileAccessException error)
{
await context.ReplyAsync(
$"The storage service denied access ({error.Status}).",
cancellationToken);
}
catch (FileUrlExpiredException)
{
await context.ReplyAsync(
"That file link expired. Attach the file again.",
cancellationToken);
}
catch (FileScopeNotSupportedException)
{
await context.ReplyAsync(
"File download isn't supported in this conversation.",
cancellationToken);
}
catch (FileException)
{
await context.ReplyAsync(
"The file couldn't be read.",
cancellationToken);
}
Tipos e valores chave:
-
FileCredentialException: Manipula a configuração de credenciais do Graph agentic-user ausente. -
FileAccessException.Status: Distingue tokens rejeitados de acesso negado. -
FileUrlExpiredException: manipula URLs de download de bot expiradas. -
FileScopeNotSupportedException: manipula a recuperação de canal ou grupo sem suporte. -
FileException: Forneça tratamento de fallback para falhas conhecidas do SDK.
| Código de status | Código de erro | Descrição | Ação do desenvolvedor |
|---|---|---|---|
| Não aplicável | FileCredentialError |
Nenhuma credencial do Graph está disponível para recuperação de arquivo de usuário agente. | Verifique as permissões do blueprint, o consentimento do administrador e a configuração de credenciais. |
| HTTP 401 ou 403 | FileAccessError |
O Microsoft Graph rejeitou o token ou negou o acesso ao item. | Inspecionar statuse, em seguida, verificar o token, o consentimento, o compartilhamento e o acesso ao item. |
| Não aplicável | FileUrlExpiredError |
A URL do arquivo pré-autorizado do bot expirou antes da recuperação ou releitura. | Peça ao usuário para anexar o arquivo novamente. Baixe uma vez e reutilize o arquivo baixado. |
| Não aplicável | FileScopeNotSupportedError |
A API de alto nível recebeu um escopo de conversa sem suporte. | Use o chat pessoal ou recupere o arquivo armazenado por meio do Microsoft Graph. |
| Não aplicável | FileError |
Uma operação de arquivo SDK conhecida falhou por outro motivo. | Mostrar uma mensagem geral do usuário e registrar o diagnóstico limpo. |
| HTTP 5xx | Erro de transporte ou serviço | O Microsoft Graph ou o armazenamento não pôde concluir a solicitação. | Tente novamente de acordo com as diretrizes de serviço e preserve o erro original. |
try {
const downloaded = await file.download();
} catch (error) {
if (error instanceof FileCredentialError) {
await send("The agent isn't configured to access this file.");
} else if (error instanceof FileAccessError) {
await send(`The storage service denied access (${error.status}).`);
} else if (error instanceof FileUrlExpiredError) {
await send('That file link expired. Attach the file again.');
} else if (error instanceof FileScopeNotSupportedError) {
await send("File download isn't supported in this conversation.");
} else if (error instanceof FileError) {
await send("The file couldn't be read.");
} else {
throw error;
}
}
Tipos e valores chave:
-
FileCredentialError: Manipula as credenciais do Graph agentic-user ausentes. -
FileAccessError.status: Distingue tokens rejeitados de acesso negado. -
FileUrlExpiredError: manipula URLs de download de bot expiradas. -
FileScopeNotSupportedError: Lidar com escopos de conversa incompatíveis. -
FileError: Forneça tratamento de fallback para falhas conhecidas do SDK.
| Código de status | Código de erro | Descrição | Ação do desenvolvedor |
|---|---|---|---|
| Não aplicável | FileCredentialError |
Nenhuma credencial do Graph está disponível para recuperação de arquivo de usuário agente. | Verifique as permissões do blueprint, o consentimento do administrador e a configuração de credenciais. |
| HTTP 401 ou 403 | FileAccessError |
O Microsoft Graph rejeitou o token ou negou o acesso ao item. | Inspecionar statuse, em seguida, verificar o token, o consentimento, o compartilhamento e o acesso ao item. |
| Não aplicável | FileUrlExpiredError |
A URL do arquivo pré-autorizado do bot expirou antes da recuperação ou releitura. | Peça ao usuário para anexar o arquivo novamente. Baixe uma vez e reutilize o arquivo baixado. |
| Não aplicável | FileScopeNotSupportedError |
A API de alto nível recebeu um escopo de conversa sem suporte. | Use o chat pessoal ou recupere o arquivo armazenado por meio do Microsoft Graph. |
| Não aplicável | FileError |
Uma operação de arquivo SDK conhecida falhou por outro motivo. | Mostrar uma mensagem geral do usuário e registrar o diagnóstico limpo. |
| HTTP 5xx | Erro de transporte ou serviço | O Microsoft Graph ou o armazenamento não pôde concluir a solicitação. | Tente novamente de acordo com as diretrizes de serviço e preserve o erro original. |
try:
downloaded = await file.download()
except FileCredentialError:
await ctx.reply("The agent isn't configured to access this file.")
except FileAccessError as error:
await ctx.reply(
f"The storage service denied access ({error.status})."
)
except FileUrlExpiredError:
await ctx.reply("That file link expired. Attach the file again.")
except FileScopeNotSupportedError:
await ctx.reply(
"File download isn't supported in this conversation."
)
except FileError:
await ctx.reply("The file couldn't be read.")
Tipos e valores chave:
-
FileCredentialError: Manipula as credenciais do Graph agentic-user ausentes. -
FileAccessError.status: Distingue tokens rejeitados de acesso negado. -
FileUrlExpiredError: manipula URLs de download de bot expiradas. -
FileScopeNotSupportedError: Lidar com escopos de conversa incompatíveis. -
FileError: Forneça tratamento de fallback para falhas conhecidas do SDK.
Diretrizes de design e práticas recomendadas
Aplique essas diretrizes para criar experiências de arquivo seguras e previsíveis. Revise-os ao projetar manipuladores e antes de implantar seu aplicativo.
- Informe aos usuários se o agente recebeu um arquivo ou está pedindo para carregar um.
- Confirmar o recebimento e o upload bem-sucedidos do arquivo.
- Explique por que o bot solicita o consentimento do arquivo antes de enviar um documento.
- Lidar com o consentimento recusado sem perguntar repetidamente ao usuário.
- Prefira o acessador de arquivo SDK do Teams em vez de analisar manualmente anexos de documentos.
- Baixe uma vez e reutilize o arquivo baixado ao processar o conteúdo repetidamente.
- Stream arquivos grandes em vez de armazenar em buffer o arquivo completo na memória.
- Limpe os nomes de arquivo fornecidos pelo carregador e use destinos controlados por aplicativo.
- Valide o conteúdo real em vez de confiar em extensões ou tipos MIME relatados.
- Não registre bytes de arquivo, credenciais, identificadores ou URLs pré-autorizadas de upload e download.
- Aplicar as políticas de expiração e limpeza a uploads pendentes de consentimento de arquivo.
- Propagar o cancelamento e lidar com falhas de HTTP, credencial, escopo e expiração.
Confira também
Use esses recursos para explorar APIs de arquivos SDK do Teams, imagens embutidas, autenticação e diretrizes de mensagens.