Extensões de esquema de diretório | Conceitos da API do Graph

Artigo
10/21/2021

Este tópico discute as extensões de diretório na API Gráfica do AD Azure, que podem ser usadas para adicionar propriedades aos objetos de diretório sem precisar de um armazenamento de dados externo. Por exemplo, se uma organização tem um aplicativo LOB (de linha de negócios) que requer uma ID do Skype para cada usuário no diretório, a API do Graph pode ser usada para registrar uma nova propriedade chamada skypeId no objeto User do diretório e, então, gravar um valor para a nova propriedade para um usuário específico. Este tópico ajudará você a entender as limitações das extensões de diretório e como elas são registradas em um diretório, além de dar exemplos de como são usadas na API do Graph.

Importante

Recomendamos que você use o Microsoft Graph em vez da API do Azure AD Graph para acessar os recursos do Azure Active Directory. Nossos esforços de implantação agora estão concentrados no Microsoft Graph e não há planos de novos aprimoramento para a API do Azure AD Graph. Há um número muito limitado de cenários para os quais a API do Azure AD Graph ainda pode ser adequada. Para saber mais, confira a postagem do blog sobre Microsoft Graph ou Azure AD Graph no Centro de Desenvolvimento do Office.

Tipos de dados de extensão

As extensões só podem ser registradas usando a API do Graph versão 1.5 ou mais recente. Os tipos de propriedade a seguir podem ser registrados:

Tipo de propriedade	Comentários
Binário	Máximo de 256 bytes.
Booliano
DateTime	Deve ser especificada no formato ISO 8601. Será armazenada em UTC.
Inteiro	Valor de 32 bits.
LargeInteger	Valor de 64 bits.
Cadeia de caracteres	Máximo de 256 caracteres.

Os tipos de propriedade acima podem ser registrados nos seguintes objetos em um diretório:

Entendendo como uma extensão é registrada

É importante compreender como uma propriedade de extensão é registrada em um diretório e como o modelo de consentimento do AD do Azure afeta seu registro. Para obter mais informações sobre o consentimento para aplicativos no Azure AD, consulte Overview of the Consent Framework (Visão geral da estrutura de consentimento) em Integrating Applications with Azure Active Directory (Integrando aplicativos ao Azure Active Directory).

Propriedades de extensão são registradas em um objeto Application dentro do diretório do desenvolvedor. Após um usuário ou administrador no diretório do desenvolvedor dar o consentimento ao aplicativo, a propriedade é adicionada ao tipo de diretório de destino e se torna acessível imediatamente no diretório do desenvolvedor. Para um aplicativo com vários locatários, quando o aplicativo tiver o consentimento concedido por um usuário em outra organização, as propriedades da extensão se tornarão acessíveis imediatamente no tipo de diretório de destino no diretório da outra organização.

Se uma organização consentir com as permissões “somente leitura” de um aplicativo com extensões registradas, as propriedades ainda ficarão acessíveis no diretório da outra organização. Além disso, as propriedades de extensão são acessíveis por um aplicativo consentido em uma organização, não apenas para aplicativo ao qual estão registradas. Outros aplicativos consentidos nessa organização podem ter valores de leitura e gravação para nova propriedade de extensão se tiverem permissões suficientes.

Se o aplicativo for excluído ou o consentimento for removido no diretório da outra organização, a propriedade de extensão ficará inacessível no objeto de diretório de destino. Se a extensão for excluída pelo aplicativo, ela também ficará inacessível no objeto de diretório de destino. Se um aplicativo com vários locatários adicionar outras propriedades de extensão após o consentimento ser concedido, essas propriedades também se tornarão acessíveis imediatamente no diretório da outra organização.

Observação: se o valor da propriedade de uma extensão for definido em um objeto e a propriedade se tornar inacessível no diretório do objeto, ela ainda será contabilizada com relação ao limite de 100 valores de propriedade de extensão do objeto. A única maneira de fazer com que o valor da propriedade deixe de ser levado em consideração depois que ele tiver sido definido é defini-lo explicitamente como null. Não será possível fazer isso se a propriedade de extensão estiver inacessível.

Cenário de exemplo

Considere este cenário: a Litware é um ISV (fornecedor independente de software) que desenvolveu um aplicativo SaaS para outras organizações usarem, e esse aplicativo requer uma propriedade de extensão denominada skypeId em um objeto User. Primeiro, a Litware registra o aplicativo em seu próprio diretório e, então, a API do Graph é chamada para registrar a propriedade de extensão no objeto Application, o que torna a propriedade acessível nos objetos User do diretório da Litware. Finalmente, a Litware torna o aplicativo apto a vários locatários, portanto, ele pode ser usado em outras organizações.

A Contoso deseja usar o aplicativo SAAS da Litware, assim um usuário ou administrador na Contoso estabelece consentimento com o aplicativo. Mediante consentimento, o aplicativo é registrado no diretório da Contoso e as propriedades de extensão registradas para o aplicativo pela Litware ficam disponíveis imediatamente no diretório da Contoso. Como a propriedade de extensão skypeId para um objeto User foi registrada pela Litware no aplicativo, a propriedade fica acessível em objetos User no diretório da Contoso. Agora, o aplicativo da Litware ou outros aplicativos com consentimento no diretório da Contoso podem acessar a nova propriedade de acordo com as permissões configuradas para o aplicativo no diretório da Contoso. Isso significa que os aplicativos, de acordo com suas permissões, podem gravar um valor para essa propriedade de extensão em um ou mais usuários no diretório. Somente usuários para os quais um valor skypeId foi gravado retornarão essa propriedade no respectivo objeto User. Esse será o caso até que a propriedade skypeId seja definida como null. Depois disso, o objeto User para o usuário em questão não retornará a propriedade.

Solicitações REST de amostra para extensões de diretório

As seguintes solicitações de amostra demonstram como registrar, exibir, gravar, ler, filtrar e retirar o registro de extensões em seu diretório. Substitua o espaço reservado <applicationObjectId> pela ID de objeto do aplicativo registrado. Você pode obter esse valor da seguinte maneira:

Vá para https://graphexplorer.cloudapp.net/, clique no link Entrar no canto superior direito e, em seguida, entre usando as credenciais de uma conta de administrador no diretório da sua organização.
Depois de entrar, clique na URL na caixa de texto de recursos (ao lado do botão GET), selecione a URL que termina em applications/ e clique em GET ou pressione Enter.
Encontre a entrada do aplicativo desejado nos resultados e copie seu valor de objectId, como: "objectId": "269fc2f7-6420-4ea4-be90-9e1f93a87a64"

Nesta seção, há solicitações de amostra para as seguintes operações:

Registrar uma extensão
Exibir extensões registradas
Gravar um valor de extensão
Remover um valor de extensão
Ler um valor de extensão
Filtrar um valor de extensão
Cancelar o registro de uma extensão

Para obter amostras completas que usam propriedades de extensão, consulte as seguintes amostras do Azure AD no Github:

WebApp-GraphAPI-DirectoryExtensions-PHP: mostra como criar e usar extensões com PHP.
WebApp-GraphAPI-DirectoryExtensions-DotNet: exibe um organograma de locatários do AAD e permite ler valores de extensão sem a necessidade de configuração.

Registrar uma extensão

A seguinte solicitação de amostra cria uma extensionProperty no objeto Application desejado.

Formato de solicitação

POST https://graph.windows.net/contoso.onmicrosoft.com/applications/<applicationObjectId>/extensionProperties?api-version=1.5 HTTP/1.1

{
    "name": "<extensionPropertyName>",
    "dataType": "<String or Binary>",
    "targetObjects": [
        "<DirectoryObject>"
    ]
}

Solicitação de amostra

POST https://graph.windows.net/contoso.onmicrosoft.com/applications/269fc2f7-6420-4ea4-be90-9e1f93a87a64/extensionProperties?api-version=1.5 HTTP/1.1
Authorization: Bearer eyJ0eXAiOiJKV1Qi...r6Xh5KVA
Content-Type: application/json
Host: graph.windows.net
Content-Length: 104

{
    "name": "skypeId",
    "dataType": "String",
    "targetObjects": [
        "User"
    ]
}

Se a operação for bem-sucedida, ela retornará um código de status HTTP 201 Criado juntamente com o nome de propriedade de extensão completo, que pode ser usado para gravar valores para o tipo de destino.

Resposta de amostra

HTTP/1.1 201 Created
...

{
    "odata.metadata": "https://graph.windows.net/contoso.onmicrosoft.com/$metadata#directoryObjects/Microsoft.WindowsAzure.ActiveDirectory.ExtensionProperty/@Element",
    "odata.type": "Microsoft.WindowsAzure.ActiveDirectory.ExtensionProperty",
    "objectType": "ExtensionProperty",
    "objectId": "dc893d45-a75b-4ccf-9b92-ce7d80922aa7",
    "name": "extension_ab603c56068041afb2f6832e2a17e237_skypeId",
    "dataType": "String",
    "targetObjects": [
        "User"
    ]
}

Exibir extensões registradas

A seguinte solicitação de amostra obtém as extensões registradas em seu objeto Application.

Formato de solicitação

GET https://graph.windows.net/contoso.onmicrosoft.com/applications/<applicationObjectId>/extensionProperties?api-version=1.5 HTTP/1.1

Solicitação de amostra

GET https://graph.windows.net/contoso.onmicrosoft.com/applications/269fc2f7-6420-4ea4-be90-9e1f93a87a64/extensionProperties?api-version=1.5 HTTP/1.1
Authorization: Bearer eyJ0eXAiOiJKV1Qi...r6Xh5KVA
Host: graph.windows.net

Se a operação tiver sido bem-sucedida, ela retornará um código de status HTTP 200 OK em conjunto com todas as informações sobre cada propriedade de extensão registrada em seu objeto Application.

Resposta de amostra

HTTP/1.1 200 OK
...

{
    "odata.metadata": "https://graph.windows.net/contoso.onmicrosoft.com/$metadata#directoryObjects/Microsoft.WindowsAzure.ActiveDirectory.ExtensionProperty",
    "value": [
        {
            "odata.type": "Microsoft.WindowsAzure.ActiveDirectory.ExtensionProperty",
            "objectType": "ExtensionProperty",
            "objectId": "dc893d45-a75b-4ccf-9b92-ce7d80922aa7",
            "name": "extension_ab603c56068041afb2f6832e2a17e237_skypeId",
            "dataType": "String",
            "targetObjects": [
                "User"
            ]
        }
    ]
}

Gravar um valor de extensão

A seguinte solicitação de amostra grava um valor de extensão para a propriedade de extensão *skypeId^ em um objeto User.

Formato de solicitação

PATCH https://graph.windows.net/contoso.onmicrosoft.com/users/username@contoso.onmicrosoft.com?api-version=1.5 HTTP/1.1

{
    "<extensionPropertyName>": <value>
}

Solicitação de amostra

PATCH https://graph.windows.net/contoso.onmicrosoft.com/users/jim@contoso.onmicrosoft.com?api-version=1.5 HTTP/1.1
Authorization: Bearer eyJ0eXAiOiJKV1Qi...r6Xh5KVA
Content-Type: application/json
Host: graph.windows.net
Content-Length: 65

{
    "extension_ab603c56068041afb2f6832e2a17e237_skypeId": "jimbob.skype"
}

Se a operação for bem-sucedida, ela retornará um código de status HTTP 204 Sem Conteúdo.

Resposta de amostra

HTTP/1.1 204 No Content

Se a tentativa de gravação ultrapassar o limite de 100 valores de extensão para o objeto, ela retornará uma resposta HTTP 403 Proibido com um código de erro "Directory_ResourceSizeExceeded" e a seguinte mensagem: "O tamanho do objeto ultrapassou o limite. Reduza o número de valores e repita a solicitação".

Remover um valor de extensão

A seguinte solicitação de amostra remove um valor de extensão que foi definido para a propriedade de extensão skypeId em um objeto User definindo o valor como null.

Formato de solicitação

PATCH https://graph.windows.net/contoso.onmicrosoft.com/users/username@contoso.onmicrosoft.com?api-version=1.5 HTTP/1.1

{
    "<extensionPropertyName>": null
}

Solicitação de amostra

PATCH https://graph.windows.net/contoso.onmicrosoft.com/users/jim@contoso.onmicrosoft.com?api-version=1.5 HTTP/1.1
Authorization: Bearer eyJ0eXAiOiJKV1Qi...r6Xh5KVA
Content-Type: application/json
Host: graph.windows.net
Content-Length: 65

{
    "extension_ab603c56068041afb2f6832e2a17e237_skypeId": null
}

Se a operação for bem-sucedida, ela retornará um código de status HTTP 204 Sem Conteúdo.

Resposta de amostra

HTTP/1.1 204 No Content

Ler um valor de extensão

A seguinte solicitação de amostra executa uma operação GET simples no usuário, que retornará os valores de propriedade padrão, assim como o novo valor de propriedade de extensão.

Formato de solicitação

GET https://graph.windows.net/contoso.onmicrosoft.com/users/username@contoso.onmicrosoft.com?api-version=1.5 HTTP/1.1

Solicitação de amostra

GET https://graph.windows.net/contoso.onmicrosoft.com/users/jim@contoso.onmicrosoft.com?api-version=1.5 HTTP/1.1
Authorization: Bearer eyJ0eXAiOiJKV1Qi...r6Xh5KVA
Host: graph.windows.net

Se a operação foi bem-sucedida, ela retornará um código de status HTTP 200 OK juntamente com o novo valor de propriedade de extensão (muitas propriedades de usuário foram removidas da resposta de amostra por questão de brevidade).

Resposta de amostra

HTTP/1.1 200 OK

{
    ...
    "usageLocation": null,
    "userPrincipalName": "Jim@contoso.onmicrosoft.com",
    "userType": "Member"
    "extension_ab603c56068041afb2f6832e2a17e237_skypeId": "jimbob.skype"
}

Filtrar um valor de extensão

A solicitação de amostra a seguir filtra os usuários pelo valor de propriedade da extensão especificada.

Observação: pesquisas de prefixo em extensões são limitadas a 71 caracteres para pesquisas de cadeia de caracteres e 207 bytes para pesquisas em extensões binárias.

Formato de solicitação

GET https://graph.windows.net/contoso.onmicrosoft.com/users?api-version=1.5&$filter=<extensionName>%20eq%20'<value>' HTTP/1.1

Solicitação de amostra

GET https://graph.windows.net/contoso.onmicrosoft.com/users?api-version=1.5&$filter=extension_ab603c56068041afb2f6832e2a17e237_skypeId%20eq%20'jimbob.skype' HTTP/1.1
Authorization: Bearer eyJ0eXAiOiJKV1Qi...r6Xh5KVA
Host: graph.windows.net

Se a operação foi bem-sucedida, ela retornará um código de status HTTP 200 OK juntamente com o objeto de usuário resultante.

Resposta de amostra

HTTP/1.1 200 OK

{
    ...
    "usageLocation": null,
    "userPrincipalName": "Jim@contoso.onmicrosoft.com",
    "userType": "Member"
    "extension_ab603c56068041afb2f6832e2a17e237_skypeId": "jimbob.skype"
}

Cancelar o registro de uma extensão

A seguinte solicitação de amostra retira o registro de uma propriedade de extensão executando a operação DELETE na ID de objeto da extensão.

Formato de solicitação

DELETE https://graph.windows.net/contoso.onmicrosoft.com/applications/<applicationObjectId>/extensionProperties/<extensionObjectId>?api-version=1.5 HTTP/1.1

Solicitação de amostra

DELETE https://graph.windows.net/contoso.onmicrosoft.com/applications/269fc2f7-6420-4ea4-be90-9e1f93a87a64/extensionProperties/dc893d45-a75b-4ccf-9b92-ce7d80922aa7?api-version=1.5 HTTP/1.1
Authorization: Bearer eyJ0eXAiOiJKV1Qi...r6Xh5KVA
Host: graph.windows.net

Se a operação for bem-sucedida, ela retornará um código de status HTTP 204 Sem Conteúdo e a propriedade de extensão terá o registro removido no aplicativo.

Resposta de amostra

HTTP/1.1 204 No Content

Comportamento e limitações da extensão

O comportamento e as limitações a seguir se aplicam a propriedades de extensão em um diretório:

Propriedades de extensão registradas para um aplicativo ficam disponíveis em um diretório quando um usuário ou administrador do diretório concede o consentimento para o aplicativo.
Após uma propriedade de extensão ficar disponível em um diretório, qualquer aplicativo com consentimento pode ler ou gravar um valor para essa propriedade de extensão para qualquer um dos objetos a que a propriedade se aplicar, de acordo com as permissões do aplicativo no diretório. Os objetos a que a propriedade de extensão se aplica são especificados na propriedade targetObjects.
No máximo 100 valores de propriedade de extensão podem ser gravados em um objeto específico em um diretório. Por exemplo, supondo que nenhum outro valor da propriedade de extensão tenha sido gravado em qualquer usuário em um diretório, se um aplicativo gravar um valor da propriedade de extensão em user1, valores de outras 99 propriedades de extensão podem ser gravados em user1 por esse aplicativo ou outro aplicativo com as permissões apropriadas no diretório. No entanto, outros usuários no diretório ainda poderão ter até 100 valores da propriedade de extensão gravados neles.
Se um aplicativo tentar definir um valor para uma propriedade de extensão adicional em um objeto para o qual 100 valores de propriedade de extensão já foram definidos, a API do Graph retornará uma resposta 403 Proibido com um código de erro "Directory_ResourceSizeExceeded" e a seguinte mensagem: "O tamanho do objeto ultrapassou o limite. Reduza o número de valores e repita a solicitação".
Se um desenvolvedor cancelar o registro (excluir) de uma propriedade de extensão de um aplicativo, essa propriedade de extensão ficará inacessível imediatamente no diretório do desenvolvedor e nos diretórios para os quais o aplicativo recebeu consentimento.
Se o aplicativo for removido do diretório do desenvolvedor, todas as propriedades de extensão registradas para esse aplicativo se tornarão inacessíveis imediatamente no diretório do desenvolvedor e em diretórios em que o aplicativo recebeu consentimento.
Se um aplicativo multilocatário tiver recebido consentimento em um diretório e, posteriormente, seu registro for cancelado (removido) no diretório – por exemplo, por um administrador usando o portal de gerenciamento do azure –, quaisquer propriedades de extensão registradas no aplicativo se tornarão inacessíveis imediatamente no diretório.
Um valor da propriedade de extensão deve ser definido explicitamente como null para ser removido de um objeto de diretório. Se um valor da propriedade de extensão for definido em um objeto de diretório e a propriedade de extensão se tornar inacessível no diretório por qualquer um dos motivos citados acima, a propriedade de extensão deixará de ficar visível no objeto de diretório. No entanto, ela ainda será levada em consideração com relação ao limite de 100 valores da propriedade de extensão para esse objeto. Até que a disponibilidade da propriedade de extensão seja restaurada - por exemplo, em alguns casos, concedendo consentimento ao aplicativo novamente -, o valor não ficará acessível para leitura ou gravação.

Recursos adicionais

Referência da API do Graph do Azure AD

Compartilhar via

Extensões de esquema de diretório | Conceitos da API do Graph

Tipos de dados de extensão

Entendendo como uma extensão é registrada

Cenário de exemplo

Solicitações REST de amostra para extensões de diretório

Registrar uma extensão

Formato de solicitação

Solicitação de amostra

Resposta de amostra

Exibir extensões registradas

Formato de solicitação

Solicitação de amostra

Resposta de amostra

Gravar um valor de extensão

Formato de solicitação

Solicitação de amostra

Resposta de amostra

Remover um valor de extensão

Formato de solicitação

Solicitação de amostra

Resposta de amostra

Ler um valor de extensão

Formato de solicitação

Solicitação de amostra

Resposta de amostra

Filtrar um valor de extensão

Formato de solicitação

Solicitação de amostra

Resposta de amostra

Cancelar o registro de uma extensão

Formato de solicitação

Solicitação de amostra

Resposta de amostra

Comportamento e limitações da extensão

Recursos adicionais

Recursos adicionais