Tipo de recurso schemaExtension (extensões de esquema)

Namespace: microsoft.graph

As extensões de esquema permitem que você defina um esquema para estender e adicionar dados personalizados digitados 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:

• user
• group
• administrativeUnit
• contact
• device
• evento (para calendários de usuário e grupo)
• message
• organização
• postagem

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 e a respetiva propriedade de extensão de esquema associada.
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. Utilize esta operação para atualizar a descrição, status, tipos de destino ou adicionar mais propriedades à definição da extensão de esquema.
Delete	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: Concatene o nome de um dos seus domínios verificados com um nome para a extensão de esquema para formar uma cadeia exclusiva neste formato, {domainName}_{schemaName}. Como exemplo, contoso_mySchema. Forneça um nome de esquema e permita que o Microsoft Graph utilize esse nome de esquema para concluir a atribuição de ID neste formato: ext{8-random-alphanumeric-chars}_{schema-name}. 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. Suporta $filter (eq).
owner	String	O appId do aplicativo que é o proprietário da extensão de esquema. O proprietário da definição de esquema tem de ser especificado explicitamente durante as operações Criar e Atualizar ou será implícito e atribuído automaticamente por Microsoft Entra ID da seguinte forma: No acesso delegado: O utilizador com sessão iniciada tem de ser o proprietário da aplicação que chama o Microsoft Graph para criar a definição da extensão de esquema. Se o utilizador com sessão iniciada não for o proprietário da aplicação de chamada, tem de especificar explicitamente a propriedade do proprietário e atribuir-lhe o appId de uma aplicação da qual é proprietário. No acesso apenas à aplicação: A propriedade do proprietário não é necessária no corpo do pedido. Em vez disso, é atribuída à aplicação de chamada a propriedade da extensão de esquema. Por exemplo, se criar uma nova definição de extensão de esquema com o Graph Explorer, tem de fornecer a propriedade 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 de esquema. Os estados possíveis são InDevelopment, 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 Ciclo de vida das extensões de esquema. Suporta $filter (eq).
targetTypes	Coleção de cadeias de caracteres	O conjunto de tipos do Microsoft Graph (que podem suportar extensões) ao qual a extensão de esquema pode ser aplicada. Selecione entre administrativeUnit, contato, dispositivo, evento, grupo, mensagem, organização, postagem, todoTask, todoTaskList ou usuário.

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.

A aplicação proprietária pode mover a extensão através de diferentes estados de um ciclo de vida, através de uma operação PATCH na respetiva propriedade status. Dependendo do estado atual, a aplicação proprietária poderá atualizar ou eliminar a extensão. Quaisquer atualizações a uma extensão de esquema devem ser sempre apenas aditivas e não interruptivas.

Estado	Comportamento de estado de ciclo de vida
InDevelopment	Estado inicial após a criação. A aplicação proprietária ainda está a desenvolver a extensão de esquema. Nesse estado, qualquer aplicativo no mesmo diretório em que o aplicativo proprietário está registrado pode ampliar as instâncias de recursos com essa definição de esquema (contanto que o aplicativo tenha permissões para esse recurso). Para uma aplicação de proprietário multi-inquilino, apenas a instância da aplicação proprietária que está num diretório diferente do diretório raiz pode expandir as instâncias de recursos com esta definição de esquema (se a aplicação 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. O aplicativo proprietário pode atualizar a definição de extensão com alterações aditivas. A aplicação proprietária pode mover a extensão de InDevelopment para o Available estado .
Disponível	A extensão do esquema está disponível para ser usada por todos os aplicativos em qualquer locatário. Depois de a aplicação proprietária definir a extensão como Available, qualquer aplicação pode adicionar dados personalizados a instâncias desses tipos de recursos especificados na extensão (se a aplicação 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. A aplicação proprietária pode mover a extensão de esquema de Available para o Deprecated estado.
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, as aplicações ainda podem ler, atualizar ou eliminar os valores de propriedade de extensão existentes.

Observação

As definições da extensão de esquema (marcadas como Available) criadas por outros programadores de outros inquilinos são visíveis para todos os programadores (ao listar 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

A representação JSON seguinte mostra o tipo de recurso.

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

Conteúdo relacionado

• Adicionar dados personalizados a recursos usando extensões
• Adicionar dados personalizados a grupos usando as extensões do esquema