Tipo de recurso schemaExtension (extensões de esquema)

  • Artigo

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 Versão.

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:

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 sua 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. Use essa operação para atualizar a descrição, status, tipos de destino ou adicionar mais propriedades à definição de 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 de seus domínios verificados com um nome para a extensão de esquema para formar uma cadeia de caracteres exclusiva neste formato, {domainName}_{schemaName}. Como exemplo, contoso_mySchema.
  • Forneça um nome de esquema e deixe o Microsoft Graph usar 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 deve ser especificado explicitamente durante as operações Criar e Atualizar, ou será implícito e atribuído automaticamente por Microsoft Entra ID da seguinte maneira:
  • No acesso delegado:
    • O usuário conectado deve ser o proprietário do aplicativo que chama o Microsoft Graph para criar a definição de extensão de esquema.
    • Se o usuário conectado não for o proprietário do aplicativo de chamada, ele deverá especificar explicitamente a propriedade do proprietário e atribuir a ele o appId de um aplicativo que ele possui.
  • No acesso somente ao aplicativo:
    • A propriedade proprietário não é necessária no corpo da solicitação. Em vez disso, o aplicativo de chamada é atribuído à propriedade da extensão de esquema.

Portanto, por exemplo, se criar uma nova definição de extensão de esquema usando o Graph Explorer, você deverá 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.

O aplicativo proprietário pode mover a extensão por diferentes estados de um ciclo de vida, usando uma operação PATCH em sua propriedade status. Dependendo do estado atual, o aplicativo proprietário pode ser capaz de atualizar ou excluir a extensão. Todas as atualizações de uma extensão de esquema sempre devem ser aditivas e não quebras.

Estado Comportamento de estado de ciclo de vida
InDevelopment
  • Estado inicial após a criação. O aplicativo proprietário ainda está desenvolvendo 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 um aplicativo proprietário de vários locatários, apenas a instância do aplicativo proprietário que está em um diretório diferente do diretório inicial 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 de 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.
  • O aplicativo proprietário 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 que o aplicativo proprietário definir a extensão como Available, qualquer aplicativo poderá adicionar dados personalizados a instâncias desses tipos de recurso 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 aplicativo proprietário 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.
  • Os aplicativos podem, no entanto, ainda ler, atualizar ou excluir os valores de propriedade de extensão 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 (listando 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 a seguir 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