Comentários Editar

Tipo de recurso schemaExtension (extensões de esquema)

  • Artigo
  • 5 minutos para o fim da leitura

Namespace: microsoft.graph

Importante

As APIs na versão /beta no Microsoft Graph estão sujeitas a alterações. Não há suporte para o uso dessas APIs em aplicativos de produção. Para determinar se uma API está disponível na v1.0, use o seletor de versão.

As extensões de esquema permitem definir um esquema para estender e adicionar dados personalizados fortemente tipados a um tipo de recurso. Os dados personalizados aparecem como um tipo complexo no recurso estendido. As extensões de esquema são suportadas pelos seguintes tipos de recursos:

Use esse recurso e métodos associados para gerenciar as definições de extensão de esquema. Para gerenciar os dados de extensão de esquema na instância de recurso estendido, use a mesma solicitação REST que você usa para gerenciar a instância de recurso. Confira o exemplo de extensão de esquema para aprender a adicionar dados personalizados aos grupos.

Para obter mais informações sobre a extensibilidade do Microsoft Graph, incluindo limites para extensões de esquema, consulte Adicionar propriedades personalizadas aos recursos usando extensões.

Métodos

Método Tipo de retorno Descrição
Criar schemaExtension Crie uma definição de extensão de esquema.
Listar schemaExtension Lista as definições de schemaExtension disponíveis e suas propriedades.
Get schemaExtension Leia as propriedades da definição de schemaExtension específica.
Atualizar schemaExtension Atualize uma definição de schemaExtension.
Excluir None Exclua uma definição de schemaExtension.

Propriedades

Propriedade Tipo Descrição
description String Descrição da extensão de esquema. Suporta $filter (eq).
id String O identificador exclusivo da definição de extensão de esquema.
Você pode atribuir um valor em uma destas duas maneiras:
  • Concatenar o nome de um de seus domínios verificados com um nome da extensão do esquema para formar uma cadeia de caracteres exclusiva neste formato, {domainName}_{schemaName}. Como exemplo, contoso_mySchema.
  • Forneça um nome de esquema e permita que o Microsoft Graph use esse nome de esquema para completar a atribuição de id neste formato: ext{8-caracteres-alfanuméricos-aleatórios}_{nome-do-esquema}. Um exemplo seria extkvbmkofy_mySchema.
Esta propriedade não pode ser alterada após a criação. Suporta $filter (eq).

Observação: recomendamos que sua id comece com uma letra alfabética entre A-Z porque os recursos de consulta podem ser limitados para as IDs que começam com inteiros.
proprietário String O appId do aplicativo que é o proprietário da extensão de esquema. Essa propriedade pode ser fornecida na criação, para definir o proprietário. Se não for fornecida, o aplicativo de chamada appId será definido como o proprietário. Em ambos os casos, o usuário conectado deve ser o proprietário do aplicativo. Então, por exemplo, se criar uma nova definição de extensão do esquema usando o Explorador do Graph, você deverá fornecer a propriedade de proprietário. Uma vez definida, essa propriedade é somente leitura e não pode ser alterada. Suporta $filter (eq).
properties Coleção extensionSchemaProperty A coleção de tipos e nomes de propriedades que compõem a definição da extensão de esquema.
status String O estado do ciclo de vida da extensão do esquema. Os estados possíveis InDevelopmentsão Available, e Deprecated. Definido automaticamente como InDevelopment na criação. Para obter mais informações sobre as possíveis transições de estado e comportamentos, consulte o ciclo de vida das extensões de esquema. Suporta $filter (eq).
targetTypes Coleção de cadeias de caracteres Conjunto de tipos do Microsoft Graph (que podem dar suporte a extensões) aos quais a extensão de esquema pode ser aplicada. Selecione entre administrativeUnit, contact, device, event, group, message, organization, post, todoTask, todoTaskList ou user.

Ciclo de vida das extensões do esquema

Quando o aplicativo cria uma definição de extensão do esquema, ele é marcado como proprietária da extensão do esquema.

O aplicativo proprietário pode mover a extensão pelos diferentes estados de um ciclo de vida, usando uma operação PATCH na propriedade status. Dependendo do estado atual, o aplicativo proprietário poderá atualizar ou excluir a extensão. Todas as atualizações para uma extensão de esquema devem ser sempre apenas aditivas e incondicionais.

Estado Comportamento de estado de ciclo de vida
InDevelopment
  • Estado inicial após a criação. O aplicativo de proprietário ainda está desenvolvendo a extensão do esquema.
  • Nesse estado, qualquer aplicativo no mesmo diretório em que o aplicativo proprietário está registrado pode estender instâncias de recurso com essa definição de esquema (se o aplicativo tiver permissões para esse recurso).
  • Para um aplicativo proprietário multilocatário, somente a instância do aplicativo proprietário que está em um diretório diferente do diretório base pode estender instâncias de recurso com essa definição de esquema (se o aplicativo tiver permissões para esse recurso) ou ler os dados da extensão.
  • O aplicativo proprietário pode atualizar a definição de extensão com alterações aditivas.
  • Somente o aplicativo proprietário pode excluir a definição de extensão.
  • O aplicativo proprietário pode mover a extensão do esquema de InDevelopment para o estado Disponível.
Disponível
  • A extensão do esquema está disponível para ser usada por todos os aplicativos em qualquer locatário.
  • Depois que o aplicativo proprietário define a extensão como Disponível, qualquer aplicativo pode simplesmente adicionar dados personalizados a instâncias desses tipos de recursos especificados na extensão (se o aplicativo tiver permissões para esse recurso). O aplicativo pode atribuir dados personalizados ao criar uma nova instância ou atualizar uma instância existente.
  • O aplicativo proprietário pode atualizar a definição de extensão com alterações aditivas. Nenhum aplicativo pode excluir a definição de extensão nesse estado.
  • O proprietário do aplicativo pode mover a extensão do esquema de Disponível para o estado Preterido.
Preterido
  • A definição de extensão de esquema não pode ser lido nem modificada.
  • Nenhum aplicativo pode ler, atualizar, adicionar novas propriedades ou excluir a extensão.
  • No entanto, os aplicativos ainda podem ler, atualizar ou excluir valores de propriedade de extensões existentes.

Observação: As definições de extensão de esquema (marcadas como Available) criadas por outros desenvolvedores de outros locatários são visíveis para todos os desenvolvedores (pela listagem de todas as extensões de esquema). Isto é diferente de outras APIs que retornam apenas os dados específicos do locatário. Por outro lado, os dados de extensão criados com base nas definições de extensão de esquema, são específicos do locatário e só podem ser acessados por aplicativos explicitamente autorizados.

Representação JSON

Veja a seguir uma representação JSON do recurso.

{
  "description": "String",
  "id": "String (identifier)",
  "owner": "String",
  "properties": [{"@odata.type": "microsoft.graph.extensionSchemaProperty"}],
  "status": "String",
  "targetTypes": ["String"]
}

Confira também