Armazenar e consultar metadados de contentor

Aplica-se a: Programador

Utilize metadados quando a sua aplicação precisar de campos estruturados em ficheiros num contentor do SharePoint Embedded. Os metadados são armazenados como colunas num fileStorageContainer e como valores de campo nos itens da unidade de contentor. A sua aplicação é responsável por criar e gerir o esquema de colunas para cada instância de contentor. Para obter a lista completa das propriedades dos recursos de contentor, veja fileStorageContainer resource type (Tipo de recurso fileStorageContainer).

Permissões e autores de chamadas suportados

Chame as APIs de metadados com um token de portador delegado ou apenas de aplicação. Utilize FileStorageContainer.Selected para aplicação e chamadas delegadas.

Os proprietários de contentores podem criar, atualizar e eliminar colunas. Os membros do contentor podem ler e listar colunas.

Escolher tipos de coluna

Os metadados do SharePoint Embedded suportam estas propriedades de tipo de coluna: boolean, choice, , currency, hyperlinkOrPicturedateTime, number, personOrGroupe text. Também suporta definições de colunas como indexed, isDeletable, isSealed, name, readOnlye type.

Os nomes das colunas têm de seguir as regras do SharePoint. Não utilize nomes que contenham !, comece com um dígito ou pontuação, contenha espaços, pareça referências de células de folha de cálculo, represente valores verdadeiros ou falsos localizados ou utilize nomes reservados como Author, Createdou Description.

Criar uma coluna

Crie uma coluna no contentor antes de escrever valores de campo em ficheiros.

POST https://graph.microsoft.com/beta/storage/fileStorage/containers/{container-id}/columns
Content-Type: application/json

{
  "description": "test",
  "displayName": "Title",
  "enforceUniqueValues": false,
  "hidden": false,
  "indexed": false,
  "name": "Title",
  "text": {
    "allowMultipleLines": false,
    "appendChangesToExistingText": false,
    "linesForEditing": 0,
    "maxLength": 255
  }
}

O pedido de criação não suporta typee o texto maxLength tem de ser menor ou igual a 255.

Observação

A partir de janeiro de 2026, as APIs da coluna de contentor (lista, criar, atualizar, eliminar colunas) também estão geralmente disponíveis no ponto final v1.0 do Microsoft Graph. Pode substituir por /beta//v1.0/ nos pedidos de coluna abaixo. O ponto final beta permanece disponível.

Gerir colunas

Utilize o ID de coluna devolvido pela operação de criação ou lista.

GET https://graph.microsoft.com/beta/storage/fileStorage/containers/{container-id}/columns
GET https://graph.microsoft.com/beta/storage/fileStorage/containers/{container-id}/columns/{column-id}
PATCH https://graph.microsoft.com/beta/storage/fileStorage/containers/{container-id}/columns/{column-id}
DELETE https://graph.microsoft.com/beta/storage/fileStorage/containers/{container-id}/columns/{column-id}

Correção de propriedades suportadas quando o esquema é alterado. Pode atualizar qualquer propriedade de uma coluna, exceto a id propriedade .

{
  "required": true,
  "hidden": false,
  "description": "This is my new column description"
}

Ler e escrever metadados de ficheiro

Os valores dos campos são armazenados nos campos do item de lista do item de unidade. Leia todos os campos ou selecione os campos de que a IU precisa.

GET https://graph.microsoft.com/beta/drives/{drive-id}/items/{item-id}/listitem/fields
GET https://graph.microsoft.com/beta/drives/{drive-id}/items/{item-id}/listitem/fields?$select=Name,Color

Patch field values to update metadata. Utilize null para limpar um valor de campo quando a coluna permite valores vazios.

PATCH https://graph.microsoft.com/beta/drives/{drive-id}/items/{item-id}/listitem/fields
Content-Type: application/json

{
  "Color": "Fuchsia",
  "Quantity": 934
}

{
  "Color": null
}

Consultar ficheiros por metadados

Utilize as opções de consulta OData em colunas personalizadas quando precisar de filtragem estruturada ou ordenação dentro de uma unidade de contentor.

GET https://graph.microsoft.com/beta/drives/{drive-id}/items?$orderby=listitem/fields/TestField asc&$filter=startswith(listitem/fields/TestField, '3')&$expand=listitem($expand=fields)

Utilize $expand=listitem($expand=fields) quando o resultado precisar de valores de campo na resposta. Crie colunas indexadas para filtros de elevada cardinalidade que a sua aplicação executa com frequência.

Para procurar em texto completo em contentores e metadados personalizados (utilizando o OWSTEXT sufixo de propriedade), veja Pesquisar contentores e ficheiros. Utilize OData $filter para consultas estruturadas numa única unidade de contentor; utilize a pesquisa de consultas de texto livre em muitos contentores.

Manter o esquema consistente

Crie as colunas necessárias durante o aprovisionamento de contentores. Armazene a versão de esquema esperada nos dados da aplicação e execute migrações quando forem introduzidas novas colunas. Evite eliminar colunas até não conhecer fluxos de trabalho, consultas, exportações ou experiências de pesquisa que dependam dos respetivos valores.

Próximas etapas

  • Last updated on