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.
Uma imagem embutida faz parte da mensagem e é renderizada diretamente em uma conversa do Microsoft Teams, em vez de aparecer como documentos armazenados na guia Compartilhado da conversa. O Teams representa cada imagem como um anexo de atividade com um tipo MIME de imagem e uma URL hospedada ou URI de dados base64.
Use o SDK do Teams para baixar imagens que os usuários colam em mensagens e enviar imagens de URLs hospedadas ou bytes na memória. Para documentos armazenados no OneDrive ou no SharePoint, consulte Enviar e receber arquivos.
Observação
No GCC High, DoD e Teams operados pela 21Vianet, os agentes podem usar um anexo de imagem base64 para incluir uma imagem em uma mensagem, embora os fluxos de trabalho de arquivo de documento não tenham suporte.
Experiência do usuário
Entenda como as imagens embutidas aparecem e se comportam para que você possa selecionar a apresentação certa para o conteúdo visual. Os usuários podem:
- Exiba uma imagem enviada por um agente com um texto de mensagem e uma imagem base64 posicionada dentro do texto de mensagem formatado.
- Cole uma imagem que renderiza em sua posição em uma mensagem composta.
- Interaja com uma imagem incluída em um Cartão Adaptável.
Use um anexo hospedado para uma imagem autônoma, conteúdo HTML/XML base64 para posicionamento exato ou um Cartão Adaptável quando a imagem pertencer ao conteúdo interativo.
Experiência do desenvolvedor
Escolha uma representação de imagem com base em onde os bytes estão armazenados e como a imagem deve aparecer. As opções a seguir correspondem à ordem de implementação neste artigo:
| Requisito | Abordagem recomendada |
|---|---|
| Receber uma imagem colada em uma mensagem | Inspecione os anexos de atividade e use o cliente HTTP do SDK autenticado |
| Enviar uma imagem ao lado do texto da mensagem | Anexo de imagem com uma URL hospedada ou URI de dados Base64 |
| Posicionar uma imagem dentro do texto formatado | Imagem Base64 em conteúdo HTML/XML |
| Adicionar uma imagem a um conteúdo interativo | Elemento do Cartão Image Adaptável |
A coleção de anexos da atividade contém a carga da imagem e todas as informações de layout HTML. As imagens embutidas não são expostas por meio do acessador de arquivo do SDK do Teams.
| Operação | Chat pessoal | Chat em grupo | Canal | Requisito |
|---|---|---|---|---|
| Receber imagens embutidas | Compatível por meio de anexos de atividade | Usar anexos de atividade | Usar anexos de atividade | Baixe com o cliente HTTP do SDK autenticado do aplicativo. |
| Enviar imagens embutidas | Com suporte | Com suporte | Com suporte | Não é necessária permissão do Graph ou entrada do usuário. |
Trabalhar com imagens embutidas
Use imagens embutidas quando os usuários ou agentes precisarem de conteúdo visual renderizado diretamente em uma conversa, em vez de como um documento armazenado. Use anexos de atividade autenticados para receber imagens e anexos de imagem ou conteúdo HTML/XML para enviá-los.
Receber imagens embutidas
Uma imagem embutida não é exposta por meio do acessador de arquivo do SDK do Teams. Uma mensagem de entrada normalmente inclui um image/* anexo com a URL de download autenticada e um text/html anexo que preserva a posição da imagem.
Use o image/* anexo como a fonte canônica. Não use a <img src> URL do anexo HTML para baixar a imagem.
using Microsoft.Extensions.DependencyInjection;
using Microsoft.Teams.Apps.Clients;
using Microsoft.Teams.Apps.Schema;
HttpClient imageClient = app.Services
.GetRequiredService<IHttpClientFactory>()
.CreateClient(nameof(ApiClient));
teams.OnMessage(async (context, cancellationToken) =>
{
TeamsAttachment? image =
context.Activity.Attachments?.FirstOrDefault(
attachment =>
attachment.ContentType is not null &&
attachment.ContentType.Value.StartsWith(
"image/",
StringComparison.OrdinalIgnoreCase) &&
attachment.ContentUrl is not null);
if (image?.ContentUrl is not Uri contentUrl)
{
return;
}
using HttpResponseMessage response =
await imageClient.GetAsync(
contentUrl,
HttpCompletionOption.ResponseHeadersRead,
cancellationToken);
response.EnsureSuccessStatusCode();
byte[] bytes =
await response.Content.ReadAsByteArrayAsync(
cancellationToken);
// Process the image bytes.
});
Principais APIs e valores:
-
nameof(ApiClient): selecione o cliente do SDK com autenticação de plataforma. -
ContentType: correspondem a umimage/*tipo MIME sem diferenciar maiúsculas de minúsculas. -
ContentUrl: Use a URL de download de imagem autenticada canônica. -
ResponseHeadersRead: comece o processamento sem armazenar em buffer o conteúdo de resposta primeiro. -
EnsureSuccessStatusCode: falham explicitamente quando a recuperação de imagem não for bem-sucedida.
app.on('message', async ({ activity }) => {
const image = activity.attachments?.find(
(attachment) =>
attachment.contentType?.toLowerCase().startsWith('image/') &&
attachment.contentUrl
);
if (image?.contentUrl) {
const response = await app.api.http.get<ArrayBuffer>(
image.contentUrl,
{ responseType: 'arraybuffer' }
);
const bytes = Buffer.from(response.data);
// Process the image bytes.
}
});
Principais APIs e valores:
-
activity.attachments: pesquise todos os anexos de mensagens recebidas. -
contentType: correspondem a umimage/*tipo MIME sem diferenciar maiúsculas de minúsculas. -
contentUrl: Use a URL de download de imagem autenticada canônica. -
app.api.http: baixe bytes com o cliente autenticado do SDK. -
responseType: Definidoarraybufferpara receber conteúdo de imagem binária.
@app.on_message
async def handle_message(ctx: ActivityContext[MessageActivity]) -> None:
image = next(
(
attachment
for attachment in (ctx.activity.attachments or [])
if attachment.content_type
and attachment.content_type.lower().startswith("image/")
and attachment.content_url
),
None,
)
if image and image.content_url:
response = await app.api.http.get(image.content_url)
image_bytes = response.content
# Process the image bytes.
Principais APIs e valores:
-
ctx.activity.attachments: pesquise todos os anexos de mensagens recebidas. -
content_type: correspondem a umimage/*tipo MIME sem diferenciar maiúsculas de minúsculas. -
content_url: Use a URL de download de imagem autenticada canônica. -
app.api.http: baixe bytes com o cliente autenticado do SDK. -
response.content: Acesse o conteúdo da imagem binária baixada.
Processe os bytes diretamente quando possível. Converta-os em base64 somente quando uma API downstream exigir e preserve o tipo MIME real do anexo.
Enviar uma imagem embutida
Uma imagem embutida de saída usa um tipo MIME de ContentType imagem e uma URL HTTPS acessível ou um URI de dados base64 no ContentUrl. O envio não carrega a imagem no OneDrive ou no SharePoint e não requer permissão do Graph ou entrada do usuário.
Escolha uma URL hospedada para imagens disponíveis externamente ou dados base64 para imagens pequenas mantidas pelo seu aplicativo e, em seguida, crie o anexo de mensagem de saída correspondente. O Teams dá suporte a imagens embutidas com os seguintes limites:
| Limite | Valor |
|---|---|
| Dimensões máximas | 1024 x 1024 pixels |
| Tamanho máximo da imagem | 1 MB |
| Formatos com suporte | PNG, JPEG e GIF |
| GIF animado | Sem suporte |
| Validação de SDK | Não executado |
Aviso
Uma imagem fora das dimensões, tamanho ou formato com suporte pode ser aceita pela API de envio, mas não consegue renderizar no cliente do Teams.
Enviar uma imagem de uma URL hospedada
Use uma URL hospedada quando a imagem já estiver disponível por meio de um ponto de extremidade HTTPS público ou for muito grande para ser incorporada com eficiência. Adicione a URL acessível e o tipo MIME correspondente a um anexo de imagem.
TeamsAttachment image = TeamsAttachment.CreateBuilder()
.WithContentType(new AttachmentContentType("image/png"))
.WithContentUrl(new Uri("https://contoso.com/charts/weekly.png"))
.WithName("weekly.png")
.Build();
await context.SendAsync(
new MessageActivityInput()
.WithText("Here is the latest chart:")
.AddAttachment(image),
cancellationToken);
Propriedades e valores chave:
-
ContentType: defina o tipo MIME correspondente aos bytes de imagem hospedada. -
ContentUrl: defina uma URL de imagem HTTPS acessível publicamente. -
Name: adicione um nome de exibição opcional para a imagem. -
AddAttachment: anexe a imagem à mensagem de saída.
app.on('message', async ({ send }) => {
await send(
new MessageActivityInput('Here is the latest chart:')
.addAttachments({
contentType: 'image/png',
contentUrl: 'https://contoso.com/charts/weekly.png',
name: 'weekly.png'
})
);
});
Propriedades e valores chave:
-
contentType: defina o tipo MIME correspondente aos bytes de imagem hospedada. -
contentUrl: defina uma URL de imagem HTTPS acessível publicamente. -
name: adicione um nome de exibição opcional para a imagem. -
addAttachments: anexe a imagem à mensagem de saída.
@app.on_message
async def handle_message(ctx: ActivityContext[MessageActivity]) -> None:
await ctx.send(
MessageActivityInput(text="Here is the latest chart:").add_attachments(
Attachment(
content_type="image/png",
content_url="https://contoso.com/charts/weekly.png",
name="weekly.png",
)
)
)
Propriedades e valores chave:
-
content_type: defina o tipo MIME correspondente aos bytes de imagem hospedada. -
content_url: defina uma URL de imagem HTTPS acessível publicamente. -
name: adicione um nome de exibição opcional para a imagem. -
add_attachments: anexe a imagem à mensagem de saída.
A URL deve estar acessível ao cliente do Teams sem credenciais de agente. Prefira essa abordagem para imagens que não sejam pequenas.
Enviar bytes de imagem como base64
Use um URI de dados base64 quando bytes de imagem existirem apenas em seu aplicativo, como para um ícone, miniatura ou gráfico gerado. Codifique os bytes, preserve o tipo MIME correto e anexe o URI de dados resultante à mensagem.
byte[] bytes = await File.ReadAllBytesAsync(
"./charts/weekly.png",
cancellationToken);
string dataUri =
$"data:image/png;base64,{Convert.ToBase64String(bytes)}";
TeamsAttachment image = TeamsAttachment.CreateBuilder()
.WithContentType(new AttachmentContentType("image/png"))
.WithContentUrl(new Uri(dataUri))
.WithName("weekly.png")
.Build();
await context.SendAsync(
new MessageActivityInput()
.WithText("Here is the latest chart:")
.AddAttachment(image),
cancellationToken);
Propriedades e valores chave:
-
dataUri: Prefixe bytes base64 com o tipo MIME correspondente. -
ContentType: corresponda ao URI dos dados e ao formato real da imagem. -
ContentUrl: Encapsule o URI de dados completo emUri. -
Name: adicione um nome de arquivo opcional que corresponda ao formato da imagem.
app.on('message', async ({ send }) => {
const bytes = await readFile('./charts/weekly.png');
await send(
new MessageActivityInput('Here is the latest chart:')
.addAttachments({
contentType: 'image/png',
contentUrl: `data:image/png;base64,${bytes.toString('base64')}`,
name: 'weekly.png'
})
);
});
Propriedades e valores chave:
-
contentUrl: Prefixe bytes base64 com o tipo MIME correspondente. -
contentType: corresponda ao URI dos dados e ao formato real da imagem. -
bytes.toString('base64'): Codifique os bytes de imagem para o URI de dados. -
name: adicione um nome de arquivo opcional que corresponda ao formato da imagem.
@app.on_message
async def handle_message(ctx: ActivityContext[MessageActivity]) -> None:
encoded = b64encode(
Path("./charts/weekly.png").read_bytes()
).decode("ascii")
await ctx.send(
MessageActivityInput(text="Here is the latest chart:").add_attachments(
Attachment(
content_type="image/png",
content_url=f"data:image/png;base64,{encoded}",
name="weekly.png",
)
)
)
Propriedades e valores chave:
-
content_url: Prefixe bytes base64 com o tipo MIME correspondente. -
content_type: corresponda ao URI dos dados e ao formato real da imagem. -
b64encode: Codifique os bytes de imagem para o URI de dados. -
name: adicione um nome de arquivo opcional que corresponda ao formato da imagem.
O Base64 aumenta o tamanho da carga útil em aproximadamente um terço. Use-o para pequenas imagens geradas e use uma URL hospedada para imagens maiores.
Posicionar uma imagem dentro do texto da mensagem
Use conteúdo HTML/XML para controlar o posicionamento e as dimensões da imagem:
string encoded = Convert.ToBase64String(
await File.ReadAllBytesAsync(
"./charts/weekly.png",
cancellationToken));
await context.SendAsync(
new MessageActivityInput()
.WithText(
$"<div>Revenue is up." +
$"<img src=\"data:image/png;base64,{encoded}\"/>" +
$"Questions?</div>")
.WithTextFormat(TextFormats.Xml),
cancellationToken);
Propriedades e valores chave:
-
src: Use um URI de dados base64 para imagens inseridas. -
TextFormats.Xml: Habilite os elementos HTML no corpo da mensagem. -
heightewidth: Adicione dimensões opcionais ao elemento de imagem.
app.on('message', async ({ send }) => {
const bytes = await readFile('./charts/weekly.png');
const encoded = bytes.toString('base64');
await send(
new MessageActivityInput(
`<div>Revenue is up.` +
`<img src="data:image/png;base64,${encoded}"/>` +
`Questions?</div>`
).withTextFormat('xml')
);
});
Propriedades e valores chave:
-
src: Use um URI de dados base64 para imagens inseridas. -
withTextFormat('xml'): Habilite elementos HTML no corpo da mensagem. -
heightewidth: Adicione dimensões opcionais ao elemento de imagem.
@app.on_message
async def send_positioned_image(
ctx: ActivityContext[MessageActivity],
) -> None:
encoded = base64.b64encode(
Path("./charts/weekly.png").read_bytes()
).decode("ascii")
await ctx.send(
MessageActivityInput(
text=(
'<div>Revenue is up.'
f'<img src="data:image/png;base64,{encoded}"/>'
'Questions?</div>'
)
).with_text_format("xml")
)
Propriedades e valores chave:
-
src: Use um URI de dados base64 para imagens inseridas. -
with_text_format("xml"): Habilite elementos HTML no corpo da mensagem. -
heightewidth: Adicione dimensões opcionais ao elemento de imagem.
Um HTTPS <img src> não é carregado nem reescrito. Em vez disso, use um anexo de imagem hospedado. Cada imagem inserida conta para o conteúdo da mensagem e exceder o limite pode rejeitar a mensagem inteira.
Para várias imagens autônomas, adicione cada anexo e selecione um layout compatível, como lista ou carrossel. Para uma imagem dentro do conteúdo interativo, use um elemento Adaptive Card Image . Para respostas transmitidas, adicione anexos somente à mensagem final porque as atividades intermediárias de digitação não carregam anexos.
Lidar com erros
Lide com as falhas de recuperação separadamente das falhas de validação e renderização de imagem para que os usuários recebam uma resposta acionável.
| Código de status | Código de erro | Descrição | Ação do desenvolvedor |
|---|---|---|---|
| HTTP 4xx | Falha na solicitação de imagem autenticada | A plataforma rejeitou a solicitação da URL da imagem de entrada. | Use o cliente HTTP do SDK autenticado, preserve o status da resposta e verifique se o aplicativo pode acessar o anexo da mensagem. |
| HTTP 5xx | Serviço de imagem não disponível | O Teams ou o serviço de anexo não puderam concluir o download. | Preserve o erro original e tente novamente de acordo com as diretrizes do serviço. |
| Não aplicável | Anexo de imagem inválido | O anexo não tem nenhum tipo MIME de imagem ou URL de conteúdo. | Ignore o anexo e inspecione os anexos de atividade restantes. |
| Não aplicável | Imagem hospedada indisponível | O cliente do Teams não pode acessar uma URL de imagem hospedada sem as credenciais do agente. | Use uma URL HTTPS acessível publicamente ou envie uma imagem base64. |
| Não aplicável | Falha na renderização da imagem | O tipo, formato, tamanho ou dimensões MIME não são suportados. | Corresponda o tipo MIME aos bytes e valide a imagem antes de enviar. |
| Não aplicável | Carga útil da mensagem rejeitada | O conteúdo de imagem Base64 faz com que a mensagem exceda seu limite de conteúdo. | Reduza o tamanho da imagem ou use uma URL hospedada. |
Diretrizes de design e práticas recomendadas
Aplique estas diretrizes para criar experiências de imagem embutida confiáveis e acessíveis. Revise-os antes de processar ou enviar conteúdo de imagem.
- Informe aos usuários qual imagem o agente recebeu ou gerou e o que ele fez com o conteúdo.
- Use o cliente HTTP do SDK autenticado para URLs de imagem de entrada.
- Pesquisar todos os anexos em vez de presumir que o primeiro anexo é uma imagem.
- Use o
image/*anexo como a fonte de download canônica, não a URL HTML<img src>. - Preserve e valide o tipo MIME da imagem real.
- Mantenha as imagens base64 pequenas e prefira URLs hospedadas para imagens maiores.
- Verifique se as URLs de imagem hospedadas estão acessíveis sem credenciais de agente.
- Valide o tamanho, as dimensões e o formato da imagem antes de enviar.
- Adicione texto alternativo significativo quando a imagem fizer parte de um Cartão Adaptável.
- Use HTML/XML somente quando o posicionamento ou as dimensões exatas da imagem forem necessários.
- Adicione anexos à mensagem transmitida final porque as atividades intermediárias de digitação não carregam anexos.
- Não registre bytes de imagem ou URLs de anexos autenticados.
- Propagar o cancelamento e preservar erros HTTP para diagnósticos.
Confira também
Use esses recursos para explorar APIs de imagem do SDK do Teams, tratamento de arquivos, cartões e diretrizes de mensagens.