Armazenar e consultar metadados de contêiner

Aplica-se a: Desenvolvedor

Use metadados quando seu aplicativo precisar de campos estruturados em arquivos em um contêiner do SharePoint Embedded. Os metadados são armazenados como colunas em um fileStorageContainer e como valores de campo nos itens da unidade de contêiner. Seu aplicativo é responsável por criar e gerenciar o esquema de colunas para cada instância de contêiner. Para obter a lista completa de propriedades de recursos de contêiner, consulte o tipo de recurso fileStorageContainer.

Permissões e chamadores com suporte

Chame as APIs de metadados com um token de portador delegado ou somente aplicativo. Use FileStorageContainer.Selected para aplicativos e chamadas delegadas.

Os proprietários e gerentes de contêiner podem criar, atualizar e excluir colunas. Os membros do contêiner podem ler e listar colunas.

Escolher tipos de coluna

Os metadados incorporados do SharePoint dão suporte a estas propriedades de tipo de coluna: boolean, choice, currency, dateTimenumberhyperlinkOrPicturepersonOrGroup, , e .text Ele também dá suporte a configurações de coluna como indexed, isDeletable, isSealed, name, readOnly, e type.

Os nomes de coluna devem seguir as regras do SharePoint. Não use nomes que contenham !, começam com um dígito ou pontuação, contêm espaços, se parecem com referências de célula de planilha, representam valores verdadeiros ou falsos localizados ou usam nomes reservados como Author, Created, ou Description.

Criar uma coluna

Crie uma coluna no contêiner antes de gravar valores de campo em arquivos.

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
  }
}

A solicitação de criação não dá suporte typee o texto maxLength deve ser menor que ou igual a 255.

Observação

A partir de janeiro de 2026, as APIs de coluna de contêiner (listar, criar, atualizar, excluir colunas) também estarão disponíveis no ponto de extremidade v1.0 do Microsoft Graph. Você pode substituir /beta/ por /v1.0/ solicitações na coluna abaixo. O ponto de extremidade beta permanece disponível.

Gerenciar Colunas

Use a ID da coluna retornada pela operação criar ou listar.

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}

Corrigir as propriedades suportadas quando o esquema for alterado. Você pode atualizar qualquer propriedade de uma coluna, exceto a id propriedade.

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

Ler e gravar metadados de arquivo

Os valores de campo são armazenados nos campos de item de lista do item de unidade. Leia todos os campos ou selecione os que sua interface do usuário 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

Corrija os valores do campo para atualizar metadados. Use 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 arquivos por metadados

Use opções de consulta OData em colunas personalizadas quando precisar de filtragem estruturada ou ordenação dentro de uma unidade de contêiner.

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)

Use $expand=listitem($expand=fields) quando o resultado precisar de valores de campo na resposta. Crie colunas indexadas para filtros de alta cardinalidade que seu aplicativo executa com frequência.

Para pesquisa de texto completo em contêineres e metadados personalizados (usando o sufixo da OWSTEXT propriedade), consulte Pesquisar contêineres e arquivos. Use o OData $filter para consultas estruturadas dentro de uma única unidade de contêiner; use a pesquisa para consultas de texto livre em muitos contêineres.

Manter o esquema consistente

Crie as colunas necessárias durante o provisionamento de contêineres. Armazene a versão do esquema esperada nos dados do aplicativo e execute migrações quando novas colunas forem introduzidas. Evite excluir colunas até saber que nenhum fluxo de trabalho, consultas, exportações ou experiências de pesquisa dependem de seus valores.

Próximas etapas

  • Last updated on