OneDrive e SharePoint no Microsoft Graph
A API REST do OneDrive é uma parte da API do Microsoft Graph que permite que seu aplicativo se conecte ao conteúdo armazenado no OneDrive e no SharePoint. A API REST é compartilhada entre o OneDrive, o OneDrive for Business, bibliotecas de documentos do SharePoint e grupos do Office, a fim de conferir ao seu aplicativo a flexibilidade para ler e armazenar o conteúdo em qualquer um desses locais, e com o mesmo código.
Essas APIs REST fazem parte do Microsoft Graph, uma API comum para serviços da Microsoft.
Para soluções atuais que usam a API do OneDrive fora do Microsoft Graph ou para soluções direcionadas ao SharePoint Server 2016, encontre mais contexto para a leitura desta documentação nas diferenças do ponto de extremidade direto.
Introdução
Para experimentar rapidamente com o Microsoft Graph e acessar arquivos, confira o Explorador do Graph e o Início Rápido do Microsoft Graph.
A API REST do OneDrive fornece alguns tipos de nível superior que representam os recursos endereçáveis na API:
Veja a seguir um exemplo do recurso driveItem.
{
"@microsoft.graph.downloadUrl":"http://public-sn3302.files.1drv.com/y2pcT7OaUEExF7EHOl",
"createdDateTime": "2014-10-31T03:37:04.72Z",
"eTag": "aRDQ2NDhGMDZDOTFEOUQzRCE1NDkyNy4w",
"id":"D4648F06C91D9D3D!54927",
"lastModifiedBy": {
"user": {
"displayName": "daron spektor",
"id": "d4648f06c91d9d3d"
}
},
"name":"BritishShorthair.docx",
"size":35212,
"file": {
"hashes":{
"sha1Hash":"cf23df2207d99a74fbe169e3eba035e633b65d94"
}
}
}
Os dados sobre um recurso são fornecidos de três maneiras:
- Propriedades (como id e name) expõem valores simples.
- Facetas (como file e photo) expõem valores complexos. Geralmente, a presença de facetas em um item indicam comportamentos ou capacidades de um item e propriedades relacionadas.
- Referências (como children) apontam para coleções de outros recursos.
Muitas solicitações podem ser adaptadas para incluir dados adicionais ou remover propriedades não utilizadas das respostas. O OneDrive usa parâmetros de consulta opcionais para habilitar essa funcionalidade. Durante toda a documentação, cada solicitação fornece mais contexto sobre quais parâmetros recebem suporte.
Por padrão, a maioria das propriedades e facetas retorna enquanto todas as referências ficam ocultas. Por questões de eficiência, recomendamos que você especifique selecionar e expandir nos dados mais importantes para você.
Confira os detalhes sobre recursos e facetas em Recursos e Facetas.
Recursos raiz do Microsoft Graph
No Microsoft Graph, a funcionalidade de OneDrive está disponível em vários recursos raiz. Esses recursos correspondem aos locais onde as bibliotecas de documento do OneDrive e do SharePoint estão disponíveis no Office 365. As entidades a seguir no Microsoft Graph podem conter uma ou mais unidades:
| Entidade | Caminho de exemplo |
|---|---|
| Usuário | /v1.0/users/{id} ou /v1.0/me |
| Grupo | /v1.0/groups/{id} |
| Site | /v1.0/sites/{id} |
Recursos raiz do OneDrive
Quando usar um recurso raiz do Microsoft Graph, seu aplicativo pode abordar recursos do OneDrive usando os caminhos a seguir:
| Caminho | Recurso |
|---|---|
/drives |
Liste os recursos drive disponíveis ao usuário autenticado. |
/drives/{drive-id} |
Acesse um drive específico usando a ID dele. |
/drives/{drive-id}/root/children |
Liste os itens na raiz de um drive específico. |
/drive/items/{item-id} |
Acesse um driveItem usando a ID dele. |
/drive/special/{special-id} |
Acesse uma pasta conhecida usando seu nome conhecido. |
/shares/{share-id} |
Acesse driveItem com a shareId ou uma URL de compartilhamento. |
Endereçamento baseado em caminho em uma unidade
É possível endereçar um driveItem com um identificador exclusivo ou no local onde esse item existe na hierarquia da unidade (ou seja, caminho do usuário). Dentro de uma solicitação de API, é possível usar dois-pontos para alternar entre o espaço do caminho da API e o espaço do caminho do usuário. Essa sintaxe é válida para qualquer driveItem endereçado por meio do espaço da API.
Também é possível fazer a transição de volta para espaço do caminho da API usando dois-pontos ao final do espaço de caminho no sistema de arquivo. Certifique-se de que os dados de usuário na URL sigam os requisitos de endereçamento e codificação de caminho.
| Caminho | Recurso |
|---|---|
/drive/root:/path/to/file |
Acesse um driveItem pelo caminho sob a raiz. |
/drive/items/{item-id}:/path/to/file |
Acesse um driveItem pelo seu próprio caminho relativo a outro item. |
/drive/root:/path/to/folder:/children |
Liste filhos ao acessar pelo caminho relativo à unidade raiz. |
/drive/items/{item-id}:/path/to/folder:/children |
Liste filhos ao acessar pelo caminho relativo a outro item. |
Pastas compartilhadas e itens remotos
O OneDrive pessoal permite que um usuário adicione um ou mais itens compartilhados de outra unidade ao próprio OneDrive.
Esses itens compartilhados aparecem como um driveItem na coleção children com uma faceta remoteItem.
Além disso, cenários nos quais os itens retornam de fora da unidade de destino também incluirão uma faceta remoteItem. Esses itens também podem retornar de pesquisa, arquivos recentes, compartilhado comigo.
Para saber mais sobre como trabalhar com pastas compartilhadas e itens remotos, confira Itens remotos e pastas compartilhadas.
Compartilhamento e permissões
Uma das ações mais comuns para OneDrive e SharePoint é o compartilhamento de itens com outras pessoas. O OneDrive permite que seu aplicativo crie links de compartilhamento, adicione permissões e envie convites para itens armazenados em uma unidade.
O OneDrive também fornece uma maneira para seu aplicativo acessar conteúdo compartilhado diretamente do link de compartilhamento.
Confira os detalhes sobre como compartilhar e consumir conteúdo compartilhado em Compartilhar itens no OneDrive.
Webhooks e notificações
O OneDrive oferece suporte ao envio de notificações por push no estilo webhook quando o conteúdo do OneDrive for alterado. Seu aplicativo pode usar essas notificações para controlar alterações quase em tempo real em vez de sondar o servidor sobre alterações.
Notas de programação
Compatibilidade de API
O OneDrive continuará evoluindo e recebendo outras funcionalidades. O caminho da API inclui um número de versão para proteger seu aplicativo contra alterações significativas. Quando houver a necessidade de uma alteração significativa, o número de versão da API será incrementado. Os aplicativos existentes que chamam o número da versão original permanecerão não afetados pela alteração. Confira a política de suporte do Microsoft Graph para saber por quanto tempo a versão d uma API tem suporte.
Uma alteração significativa é uma alteração no formato de uma solicitação ou resposta que remove ou altera um comportamento documentado existente ou remove um elemento da definição de um recurso. Não é uma alteração significativa adicionar outras ações, propriedades, facetas ou referências a um recurso.
É possível que a API exponha recursos adicionais não documentados periodicamente. Esses recursos não devem ser utilizados até que estejam documentados. Não assuma que o comportamento atual que se afasta do documentação persistirá.
Continuaremos fazendo alterações não significativas na versão existente da API, incluindo a adição de facetas, propriedades e recursos à API. Assim, qualquer código que chame a API precisa:
- Ser resiliente às outras propriedades adicionadas às respostas em JSON. Não há problema em ignorá-las.
- Não tenha dependência da ordem de propriedades retornadas nas respostas em JSON.
- Use somente caminhos de API, recursos, propriedades e valores enumerados documentados. Não há garantia de consistência para valores não documentados.
- Todas as URLs retornadas pela API do OneDrive devem ser tratadas como URLs opacas. Seu aplicativo não deve fazer suposições sobre o formato ou parâmetros nessas URLs. Elas estão sujeitas a alterações sem aviso prévio.
Limitação
O OneDrive possui limites para garantir que indivíduos e aplicativos não afetem negativamente a experiência de outros usuários. Quando uma atividade ultrapassar os limites do OneDrive, as solicitações da API serão rejeitadas por um período. O OneDrive também pode retornar um cabeçalho Retry-After com o número de segundos que seu aplicativo deve aguardar antes de enviar mais solicitações.
HTTP/1.1 429 Too Many Requests
Retry-After: 3600
Trabalhar com blocos de anotações do OneNote
Observação: Embora OneDrive armazene os blocos de anotações do OneNote, não use a API do OneDrive para trabalhar com eles. Em vez disso, use a API do OneNote.
Validação contínua da documentação
Como parte do nosso compromisso com uma documentação de alta qualidade, desenvolvemos um processo por meio do qual a validade das amostras e exemplos em nossa documentação é testada como parte de cada check-in. Chamamos isso de validação contínua da documentação.
Cada vez que uma alteração é feita em nossa documentação, validamos se tudo funciona conforme documentado no serviço. Quando criamos uma nova compilação do serviço, validamos se os exemplos em nossa documentação também continuam funcionando. Isso ajuda a garantir o funcionamento esperado de tudo o que estiver documentado, mesmo quando novas atualizações forem disponibilizadas.
Para saber os detalhes da compilação mais recente, confira a Página de status de compilação do AppVeyor para nosso repositório documentação.
Tópicos relacionados
Os tópicos a seguir contêm visões gerais de alto nível de outros conceitos que se aplicam à API do OneDrive.