OneDrive API: IA para obter links de arquivos

resposta: O que a IA deve retornar do OneDrive

A resposta que uma IA deve fornecer quando solicitada a buscar links no OneDrive deve ser precisa e reproduzível. Primeiro, retorne as URL(s) compartilháveis diretas e o webUrl do item. Em seguida inclua metadados como id do item, nome, tamanho, tipo MIME, nível de permissão e expiração quando aplicável. Registre também quem criou o link compartilhado e o carimbo de data/hora. Para auditorias, a resposta deve incluir o tipo de permissão (anônima, organização, pessoas específicas), expiração e uma breve justificativa para a criação. Isso ajuda as equipes técnicas e de operações a verificar a alteração rapidamente. A IA também deve observar se o link compartilhado já existia ou foi criado recentemente. Finalmente, adicione uma curta pontuação de confiança e a proveniência para que um humano possa verificar a fonte.

Aceite estas entradas do usuário. Devem ser suportadas: nome do arquivo, ID do arquivo, caminho da pasta, URL externa (por exemplo um link do Google Drive) ou uma consulta em linguagem natural. A IA deve mapear uma consulta em linguagem natural para uma consulta determinística em grafo e então localizar o arquivo exato. Se aparecerem múltiplos candidatos, a resposta deve mostrar as melhores correspondências e pedir ao usuário para confirmar. Se o usuário fornecer uma URL, a IA deve tentar resolver um item equivalente no OneDrive e apresentar um link compartilhado existente se houver correspondência. Se não existir, a IA deve criar um link compartilhado com um escopo explícito e retorná-lo.

Comportamento esperado. Primeiro, prefira um link compartilhado existente se esse link corresponder ao escopo e à expiração solicitados. Em seguida, crie um novo link usando o escopo de permissão de menor privilégio que satisfaça a solicitação. Por exemplo, prefira organização em vez de anônimo, a menos que o usuário solicite explicitamente anônimo. Além disso, evite criar links anônimos duplicados para o mesmo item; em vez disso, reutilize ou revogue conforme as políticas determinarem. A IA deve também verificar permissões e só criar links que o usuário solicitante possa criar.

Lista curta para testes de aceitação. 1) O webUrl retornado abre o arquivo pretendido e respeita os controles de acesso. 2) O escopo retornado corresponde à permissão solicitada. 3) A expiração e os metadados estão presentes e corretos. 4) A operação é auditable em logs e mostra o principal criador. 5) A IA inclui proveniência e uma pontuação de confiança para que um humano possa verificar antes de compartilhar externamente. Se o arquivo for sensível, a resposta deve sinalizá-lo para aprovação por um gerente ou solicitar escalonamento ao suporte técnico. Para equipes que usam virtualworkforce.ai, esse padrão de resposta integra-se diretamente com um agente de e-mail sem código, de modo que as equipes de operações possam colar links verificados em respostas sem procurar nos sistemas, o que aumenta a produtividade e reduz erros.

arquivo e link: How to locate a file and generate a shareable link

Encontre um arquivo no OneDrive usando três métodos comuns. Primeiro, resolva o driveItem ID se você já o possuir. Segundo, percorra o caminho da pasta e resolva cada segmento até encontrar o item. Terceiro, use pesquisa de conteúdo via Microsoft Graph Search para corresponder nome de arquivo ou conteúdo. Para solicitações entre plataformas, a IA pode aceitar uma URL externa e tentar mapeá-la para um arquivo armazenado no OneDrive. Se ocorrerem múltiplos resultados, retorne os principais candidatos e peça ao usuário confirmar qual arquivo deve ser usado.

Para gerar um link, chame o endpoint createLink. Use POST /drive/items/{itemId}/createLink com corpo { “type”:”view”,”scope”:”anonymous” } para uma visualização anônima. A resposta típica contém um campo webUrl que é a URL compartilhada. Sempre prefira o escopo de menor privilégio que atenda ao requisito. Se o arquivo estiver em SharePoint ou em um site de equipe, o mesmo endpoint createLink funciona, mas você deve direcionar para o drive e o itemId corretos. Observe que nomes duplicados podem existir em pastas diferentes; confirme o caminho da pasta ou o parentId antes de criar um link compartilhado. Verifique também permissões herdadas de pasta que possam bloquear a criação de links.

Exemplo de requisição e resposta HTTP (curto). Request: POST https://graph.microsoft.com/v1.0/me/drive/items/{itemId}/createLink body { “type”:”view”,”scope”:”organization” }. Response excerpt: { “link”: { “webUrl”: “https://onedrive.live.com/…”, “scope”: “organization”, “type”: “view” }, “id”: “…” } O webUrl é o link compartilhado que seus usuários abrirão. Quando a automação chama createLink, capture a resposta e registre o webUrl e o escopo.

Cenários de borda a tratar. Se o arquivo estiver dentro de uma pasta compartilhada, talvez você não precise de um novo link compartilhado. Para arquivos importantes e altamente sensíveis, exija uma etapa de aprovação antes de gerar um link anônimo. Se o item estiver no OneDrive for Business e for coberto por retenção ou DLP, a chamada API pode falhar. Nesses casos retorne um erro claro e oriente o usuário a solicitar permissão ou a baixar uma cópia por um processo controlado. Para equipes que precisam de auditabilidade, registre toda ação createLink, quem solicitou e se a IA criou ou reutilizou um link compartilhado. Para ajuda rápida com localização de arquivos, consulte um guia de localizador de arquivos como este que explica padrões de pesquisa de caminho e contextos de site (Guia passo a passo para localizar arquivos no SharePoint usando uma ferramenta de localização de arquivos).

api: Microsoft Graph endpoints, requests and permission models

Ao integrar com o OneDrive use o Microsoft Graph como o gateway principal. Endpoints-chave que você usará incluem createLink e invite para compartilhamento direcionado, /search/query para pesquisa de conteúdo, e /subscriptions para receber webhooks de alterações em driveItem. Também chame /drives e /sites quando o arquivo estiver em uma coleção de sites. O Graph oferece modelos de permissão delegada e de aplicativo. Escolha o modelo certo para o seu fluxo de trabalho.

Orientação sobre permissões. Prefira permissões delegadas onde a IA atua no contexto do usuário. Use Files.ReadWrite ou Sites.ReadWrite.All sob consentimento delegado para fluxos interativos. Só use permissões de aplicativo quando necessário e após consentimento do administrador. Para acesso em nível de aplicativo, exija Files.ReadWrite.All e Sites.ReadWrite.All e restrinja com acesso condicional. Siga o princípio do menor privilégio e registre o uso de tokens. Se sua solução realizar operações em lote, divida o trabalho em lotes menores para evitar limites de taxa.

Conselhos de segurança. Audite e registre chamadas createLink e mantenha registros para conformidade. Use MFA e acesso condicional para reduzir riscos. Faça varredura por links compartilhados anonimamente e aplique expiração automática onde a política organizacional exigir. Para monitoramento em tempo real implemente subscriptions e um receptor de webhook para que você possa reagir a movimentações, exclusões ou alterações de permissão. Plataformas de serviço e hubs de integração documentam padrões para workflows baseados em eventos, por exemplo a documentação do ServiceNow para o conector do OneDrive (Microsoft OneDrive Spoke – ServiceNow).

Tratamento de erros e limites. Trate respostas 4xx e 5xx com graça. Refaça em falhas transitórias 5xx com backoff exponencial. Se vir erros sobre permissões, apresente passos claros de remediação. Também proteja-se contra compartilhamento acidental excessivo escaneando respostas por escopos anônimos e solicitando aprovação. Para ajuda de codificação consulte a documentação oficial do createLink e a visão geral de permissões no Microsoft Graph. Para ajuda da comunidade lembre-se que perguntas frequentemente aparecem em fóruns de desenvolvedores como Stack Overflow e Microsoft Q&A quando precisar de exemplos ou reportar comportamento inesperado.

copilot e arquivos do OneDrive: How Copilot integrates to fetch, summarise and share content

O Copilot trabalha através do Microsoft Graph para interagir com arquivos do OneDrive. Ele age no contexto do usuário e usa permissões delegadas. O fluxo típico é simples. O usuário faz uma pergunta. O Copilot resolve o arquivo ou arquivos alvo via uma consulta. Então o Copilot lê o conteúdo, pode resumir e, quando solicitado, criará um link compartilhado. Esse padrão mantém a trilha de auditoria e respeita o conjunto de permissões do usuário.

As capacidades incluem resumir, comparar versões, extrair links incorporados em documentos e gerar um link compartilhado quando o usuário solicitar. Por exemplo, um prompt pode pedir ao Copilot para “resumir o arquivo Excel mais recente na minha pasta Reports e me dar um link compartilhado.” O Copilot encontrará o arquivo Excel correto, lerá células chave, produzirá um breve resumo e chamará createLink para retornar um link compartilhado. Ao resumir, o Copilot deve mostrar a proveniência: nome do arquivo, carimbo de modificação e onde o conteúdo foi lido. Isso reduz o risco de alucinações e permite que o usuário verifique a fonte.

Fluxo prático e salvaguardas. Primeiro, exija consentimento explícito do usuário antes de criar um link anônimo. Segundo, mostre o resumo derivado e o caminho do arquivo para que o usuário possa confirmar. Terceiro, anexe uma nota de auditoria à operação. Se o arquivo estiver em um site de equipe, o Copilot deve esclarecer se o usuário quer escopo organização ou anônimo. A integração do Copilot pode acelerar tarefas para equipes que gerenciam muitos documentos. Para equipes de logística, por exemplo, um agente sem código da virtualworkforce.ai pode buscar links para arquivos armazenados no OneDrive e então redigir respostas de e-mail com contexto que incluem o link. Isso reduz o tempo de manuseio e melhora a consistência das respostas.

Riscos e mitigações. Verifique o conteúdo-fonte antes de agir. Se o documento for sensível ou sinalizado por políticas de conformidade, encaminhe a solicitação para um fluxo de aprovação. Mantenha um humano no loop para compartilhamentos de alto risco. Por fim, mantenha logs e revise links compartilhados periodicamente como parte das atualizações de segurança e governança.

cloud integrate: Events, webhooks, monitoring and security for cloud workflows

Integrar um fluxo de IA com o OneDrive significa pensar em eventos e monitoramento. Use subscriptions do Microsoft Graph para receber webhooks de alterações em driveItem. Quando arquivos se movem, mudam ou as permissões são atualizadas, você pode acionar automações que auditam ou revogam links. Para fluxos em tempo real, subscreva eventos de drive e site e garanta que seu receptor reconheça as notificações rapidamente. Plataformas de serviço e hubs de integração documentam padrões para subscrever e reagir a mudanças.

Monitoramento e governança. Acompanhe ações createLink e mapeie-as para um principal criador e um tíquete ou justificativa. Escaneie por links anônimos e ou expire-os automaticamente ou sinalize-os para revisão. Use DLP, políticas de retenção e acesso condicional para limitar exposição. Revisões periódicas devem verificar arquivos com acesso amplo e arquivos importantes com escopos públicos. Também automatize padrões seguros: não permita compartilhamentos anônimos para pastas que contenham dados regulados, a menos que aprovado explicitamente.

Controles de segurança a aplicar. Exija MFA para quem cria compartilhamentos. Use revisões de acesso para remover permissões obsoletas. Aplique fluxos de aprovação para compartilhamento externo e use motores de política para bloquear ou avisar quando a IA tentar gerar um link compartilhado para um arquivo classificado como sensível. Se você opera em um setor regulado, consulte o suporte Microsoft e a documentação para orientações de conformidade mais recentes. Para tratamento de incidentes, registre o token usado, o endereço IP e a ação para poder rastrear problemas até o principal iniciador.

Padrões de automação. Use subscriptions para enviar eventos a ferramentas de automação. Depois chame createLink ou invite somente após verificações de política. Para operações em lote, divida tarefas e inclua retropressão para evitar limites de taxa. Inclua também uma etapa de aprovação humana quando o fluxo precisar gerar um link compartilhado para destinatários externos. Para equipes que usam virtualworkforce.ai, integre as mesmas verificações baseadas em webhook para que o agente de e-mail só insira links validados em respostas de saída. Essa abordagem melhora a produtividade e mantém a conformidade enquanto você automatiza tarefas rotineiras.

recursos adicionais: Docs, sample code and next steps

Leia as referências oficiais primeiro. A referência do createLink e a visão geral de permissões do Microsoft Graph são leituras obrigatórias. Revise também a orientação para subscriptions e webhooks. Para notas de integração com o Copilot consulte os recursos da Microsoft sobre experiências conectadas e o Copilot para Microsoft 365 para entender como consentimento e acesso delegado funcionam. Se precisar localizar arquivos dentro de sites, um guia de localizador de arquivos explica estratégias de pesquisa e resolução de caminhos (Locate files in SharePoint).

Exemplo HTTP curto (createLink). POST https://graph.microsoft.com/v1.0/me/drive/items/{itemId}/createLink Content-Type: application/json Authorization: Bearer {token} Body: { “type”: “view”, “scope”: “organization” } Exemplo de resposta inclui “webUrl” que é o link compartilhado. Use esse webUrl em e-mails ou na resposta de API para seu aplicativo cliente. Lembre-se de registrar quem solicitou o link e se a IA criou ou reutilizou um link compartilhado.

Trecho JavaScript (muito curto). const res = await fetch(‘https://graph.microsoft.com/v1.0/me/drive/items/’+id+’/createLink’, { method: ‘POST’, headers: { ‘Authorization’:’Bearer ‘+token, ‘Content-Type’:’application/json’ }, body: JSON.stringify({ type:’view’, scope:’organization’ }) }); const data = await res.json(); console.log(data.link.webUrl);

Trecho C# (muito curto). var requestUrl = $”/me/drive/items/{id}/createLink”; var body = new { type = “view”, scope = “organization” }; var result = await graphClient.HttpProvider.SendAsync(new HttpRequestMessage(HttpMethod.Post, requestUrl) { Content = new StringContent(JsonConvert.SerializeObject(body), Encoding.UTF8, “application/json”) });

Próximos passos sugeridos. 1) Execute um pequeno demo com permissões delegadas e uma conta de teste. 2) Habilite subscriptions e registre eventos de driveItem. 3) Adicione uma política para expirar automaticamente links anônimos. 4) Teste prompts do Copilot que solicitem um link compartilhado e verifique a proveniência. Se você precisar de integração específica por domínio — como redigir e-mails logísticos que incluam links validados — veja guias relacionados sobre correspondência automatizada e IA para comunicação com agentes de carga para reduzir o tempo de manuseio e erros (correspondência logística automatizada, IA para comunicação com agentes de carga). Para ajuda da comunidade de desenvolvedores procure no Stack Overflow e no Microsoft Q&A por padrões e exemplos. Por fim, note a escala: o OneDrive atende mais de 250 milhões de usuários mensais ativos globalmente, o que explica por que permissões e governança cuidadosas importam em ambientes de produção (How Secure is OneDrive? – Mimecast).

Perguntas Frequentes

Como a IA encontra um arquivo específico no OneDrive?

A IA usa ou um driveItem ID, uma caminhada pelo caminho da pasta, ou uma consulta de conteúdo via Microsoft Graph. Se a entrada for ambígua, a IA retorna as principais correspondências e pede ao usuário confirmar o arquivo exato.

A IA pode criar um link compartilhado anônimo para qualquer arquivo?

A IA pode solicitar um link compartilhado anônimo usando createLink, mas políticas e DLP podem bloquear a ação. Sempre imponha aprovação ou expiração automática para compartilhamentos anônimos.

Quais permissões o aplicativo precisa para gerar links compartilhados?

Para ações de usuário prefira permissões delegadas como Files.ReadWrite. Para automação não assistida você precisa de permissões de aplicativo como Files.ReadWrite.All e consentimento de administrador. Aplique o menor privilégio e registre o uso de tokens.

Como audito quem criou um link compartilhado?

Registre cada chamada createLink com o principal, timestamp e itemId. Use logs de atividade do Graph e sua própria loja de auditoria para combinar essas informações em revisões.

O Copilot resume arquivos antes de criar um link compartilhado?

O Copilot pode resumir e então criar um link compartilhado mediante solicitação. Ele deve mostrar proveniência — nome do arquivo, última modificação e onde o conteúdo foi lido — para reduzir alucinações e permitir que os usuários verifiquem a fonte.

O que devo fazer se uma chamada createLink retornar um erro?

Verifique o código HTTP e a mensagem de erro. Para erros 4xx relacionados a permissões apresente passos de remediação. Para erros 5xx transitórios tente novamente com backoff. Para limites de taxa reduza a velocidade das requisições e divida operações em lotes.

Como posso prevenir o compartilhamento público acidental de arquivos importantes?

Implemente regras DLP, exija aprovações para links anônimos e execute revisões periódicas de acesso. Também configure expiração automática para qualquer link compartilhado externamente e monitore a criação de links.

Onde posso encontrar exemplos para usar o endpoint createLink?

Consulte a documentação do Microsoft Graph sobre createLink e exemplos da comunidade em fóruns de desenvolvedores. Você também pode revisar padrões de integração na documentação do ServiceNow para workflows baseados em eventos (OneDrive Spoke).

Posso mapear uma URL do Google Drive para um arquivo armazenado no OneDrive?

A IA pode tentar resolver uma URL externa e então pesquisar no OneDrive por um nome de arquivo ou conteúdo correspondente. Se houver correspondência, a IA retornará um link compartilhado e anotará a proveniência.

Com quem devo entrar em contato para suporte Microsoft ou atualizações de segurança?

Use os canais de suporte da Microsoft ou a comunidade de suporte Microsoft para incidentes de produto. Para atualizações de segurança siga a documentação da Microsoft e avisos de fornecedores sobre o OneDrive e o Graph.