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

Artigo
01/26/2016

Este tópico descreve as extensões de diretórios na AD Graph API do Azure, que pode ser utilizado para adicionar propriedades de objetos de diretório sem necessidade de um arquivo de dados externas. Por exemplo, se uma organização tiver uma aplicação de linha de negócio (LOB) que requer um Id de Skype para cada utilizador no diretório, a Graph API pode ser utilizada para registar uma nova propriedade denominada skypeId no objeto de utilizador do diretório e, em seguida, escrever um valor para a nova propriedade para um utilizador específico. Este tópico irá ajudá-lo a compreender as limitações das extensões de diretório, como o estão registados num diretório e fornecem exemplos de como são utilizados na Graph API.

Importante

Recomendamos vivamente que utilize Microsoft Graph em vez do AD Graph API do Azure para aceder aos recursos do Azure Active Directory. A nossa esforços de desenvolvimento são agora concentrated no Microsoft Graph e estão a ser planeados sem melhoramentos adicionais para AD Graph API do Azure. Existem um número muito limitado de cenários para o qual AD Graph API do Azure ainda poderá ser apropriado; Para obter mais informações, consulte o Microsoft Graph ou o Azure AD Graph blogue no Dev Center do Office.

Tipos de dados de extensão

As extensões só podem ser registadas com a Graph API versão 1,5 ou mais recente. Os seguintes tipos de propriedade podem ser registados:

Tipo de propriedade	Observações
Binário	máximos de 256 bytes.
Booleano
DateTime	Tem de ser especificado no formato ISO 8601. Será armazenado em UTC.
Número inteiro	valor de 32 bits.
LargeInteger	valor de 64 bits.
Cadeia	máximo de 256 carateres.

Os tipos de propriedade acima podem ser registados nos seguintes objetos num diretório:

Compreender a forma como uma extensão está registada

É importante compreender a forma como uma propriedade de extensão está registada num diretório e Azure como modelo de consentimento do AD afeta o respetivo registo. Para mais informações sobre consentimento de aplicação no Azure AD, consulte descrição geral do Framework consentimento no integrar aplicações com o Azure Active Directory.

Propriedades da extensão estão registadas num aplicação objeto no diretório do programador. Depois da aplicação foi consentiu por um utilizador ou um administrador no diretório do programador, a propriedade é adicionada ao tipo de diretório de destino e fica imediatamente disponível no diretório do programador. Para uma aplicação multi-inquilino, quando a aplicação é concedida consentimento por um utilizador ou um administrador na outra organização, as propriedades de extensão tornar-se imediatamente acessíveis no tipo de diretório de destino no diretório da outra organização.

Se uma organização permitir como "só de leitura" permissões para uma aplicação com extensões registadas, as propriedades ainda deixará de estar acessíveis no diretório da outra organização. Além disso, as propriedades de extensão podem ser acedidas por qualquer aplicação consented numa organização, não apenas para a aplicação à qual estão registados. Outras aplicações consented na organização possam ler ou escrever valores para a nova propriedade de extensão, se tiverem permissões suficientes.

Se a aplicação for eliminada ou consentimento é removido no diretório da outra organização, a propriedade de extensão torna-se inacessíveis no objeto de diretório de destino. Se eliminar a extensão pela aplicação, também torna-se inacessíveis no objeto de diretório de destino. Se uma aplicação multi-inquilino adiciona as propriedades de extensão adicionais após concessão da consentimento, estas propriedades fiquem imediatamente disponível no diretório da outra organização.

Tenha em atenção: se o valor de uma propriedade de extensão é definido num objecto e essa propriedade torna-se inacessível no diretório desse objeto, a propriedade ainda é contabilizada nas limite esse objeto de 100 valores de propriedade de extensão. É a única forma de remover o valor da propriedade de consideração depois de ter sido definido para definir explicitamente como nulo. Não é possível fazê-lo se a propriedade de extensão não está acessível.

Cenário de exemplo

Considere o seguinte cenário: Litware é um fabricante independente de software (ISV) que desenvolveu uma aplicação SaaS de outras organizações utilizar e esta aplicação necessita de uma propriedade de extensão com o nome skypeId num utilizador objeto. Litware regista primeiro a aplicação no seu próprio diretório e, em seguida, a Graph API é chamada para registar a propriedade de extensão no aplicação objeto, o que faz com que a propriedade acessível em objetos de utilizador no diretório da Litware. Por fim, Litware faz com que a multi-inquilino de aplicação com capacidade para que possa ser utilizado em outras organizações.

A Contoso pretende utilizar a aplicação SaaS a da Litware, pelo que um utilizador ou o administrador da Contoso permitir à aplicação. Após o consentimento, a aplicação está registada no diretório da Contoso e as propriedades de extensão registado para a aplicação por Litware imediatamente fique disponível no diretório da Contoso. Uma vez que o skypeId propriedade de extensão para um objeto de utilizador foi registada por Litware na aplicação, a propriedade fica acessível em utilizador objetos no diretório da Contoso. Aplicação da litware ou outras aplicações consented no diretório da Contoso agora podem aceder a nova propriedade, de acordo com as permissões configuradas para essa aplicação no diretório da Contoso. Isto significa que aplicações, de acordo com as suas permissões, podem escrever um valor para essa propriedade de extensão num ou mais utilizadores no diretório. Apenas os utilizadores para o qual um skypeId foi escrito valor irá devolver essa propriedade no respetivo utilizador objeto. Este será o caso até o skypeId propriedade está definida como nulo, após o qual o objeto de utilizador de tempo para que o utilizador já não irá devolver a propriedade.

Pedidos REST de exemplo para extensões de diretórios

Os pedidos de exemplo seguintes mostram como registar, ver, escrever, ler, filtrar e anular o registo extensões no seu diretório. Substitua o <applicationObjectId> marcador de posição com o ID de objeto. da aplicação registada Pode obter este valor da seguinte forma:

Aceda a https://graphexplorer.cloudapp.net/, clique em de sessão associar no canto superior direito e, em seguida, inicie sessão com as credenciais para uma conta de administrador no diretório da sua organização.
Depois de ter sessão iniciada, clique no URL na caixa de texto de recursos (junto a obter botão) e selecione o URL que termina em aplicações / e, em seguida, clique em obter ou clique em de introduza chave.
Localizar a entrada de aplicação pretendida na lista de resultados e, em seguida, copie o objectId valor, tal como o seguinte: "objectId": "269fc2f7-6420-4ea4-be90-9e1f93a87a64"

Nesta secção, existem pedidos de exemplo para as seguintes operações:

Registar uma extensão
Visualize as extensões registadas
Escrever um valor de extensão
Remover um valor de extensão
Ler um valor de extensão
Filtrar um valor de extensão
Anular o registo de uma extensão

Para exemplos completos que utilizam as propriedades de extensão, consulte os seguintes exemplos nos exemplos do Azure AD no Github:

WebApp GraphAPI-DirectoryExtensions PHP: mostra como criar e utilizar extensões com o PHP.
WebApp-GraphAPI-DirectoryExtensions-DotNet: apresenta um gráfico de org de inquilino do AAD e permite ler valores de extensão direito a box.

Registar uma extensão

O pedido de exemplo seguinte cria um extensionProperty no pretendido aplicação objeto.

Formato do pedido

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

Exemplo de pedido

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 foi concluída com êxito, irá devolver um código de estado HTTP 201 criado juntamente com o nome de propriedade de extensão completamente qualificado, o que pode ser utilizado para escrever 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"
    ]
}

Visualize as extensões registadas

O pedido de exemplo seguinte obtém as extensões registadas no seu aplicação objeto.

Formato do pedido

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

Exemplo de pedido

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 foi concluída com êxito, irá devolver um código de estado HTTP 200 OK juntamente com todas as informações sobre cada propriedade de extensão registada no seu objeto de aplicação.

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

Escrever um valor de extensão

O pedido de exemplo seguintes escreve um valor de extensão para a * skypeId ^ propriedade de extensão num utilizador objeto.

Formato do pedido

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

{
    "<extensionPropertyName>": <value>
}

Exemplo de pedido

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 foi concluída com êxito, irá devolver um código de estado HTTP 204 não conteúdo.

Resposta de amostra

HTTP/1.1 204 No Content

Se a tentativa de escrever excede o limite de valor de 100 extensão para o objeto, irá devolver uma resposta HTTP 403 Proibido com um código de erro de "Directory_ResourceSizeExceeded" e a seguinte mensagem: "o tamanho do objeto excedeu o limite. Reduza o número de valores e repita o pedido de".

Remover um valor de extensão

O pedido de exemplo seguintes remove um valor de extensão que foi anteriormente definido para o skypeId propriedade de extensão num utilizador objeto definindo o valor nulo.

Formato do pedido

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

{
    "<extensionPropertyName>": null
}

Exemplo de pedido

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 foi concluída com êxito, irá devolver um código de estado HTTP 204 não conteúdo.

Resposta de amostra

HTTP/1.1 204 No Content

Ler um valor de extensão

O pedido de exemplo seguinte executa uma operação GET simples no utilizador, que irá devolver os valores de propriedade padrão, bem como o novo valor de propriedade de extensão.

Formato do pedido

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

Exemplo de pedido

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 concluída com êxito, irá devolver um código de estado HTTP 200 OK juntamente com o novo valor de propriedade de extensão (muitas das propriedades de utilizador foram removidos da resposta de amostra de uma forma abreviada).

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

O pedido de exemplo seguintes filtra os utilizadores pelo valor da propriedade de extensão especificado.

Tenha em atenção: prefixo pesquisas em extensões estão limitadas a 71 carateres para a cadeia de procura e 207 bytes para pesquisas em extensões de binárias.

Formato do pedido

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

Exemplo de pedido

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 concluída com êxito, irá devolver um código de estado HTTP 200 OK, juntamente com o objeto de utilizador resultante.

Resposta de amostra

HTTP/1.1 200 OK

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

Anular o registo de uma extensão

O pedido de exemplo seguintes anula o registo de uma propriedade de extensão ao efetuar uma operação de eliminação de ID de objeto de extensão.

Formato do pedido

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

Exemplo de pedido

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 foi concluída com êxito, irá devolver um código de estado HTTP 204 não conteúdo e a propriedade de extensão irão ser registo anulada com êxito na aplicação.

Resposta de amostra

HTTP/1.1 204 No Content

Comportamento da extensão e limitações

O seguinte comportamento e limitações aplicam-se às propriedades de extensão num diretório:

As propriedades de extensão registadas para uma aplicação fiquem disponíveis num diretório quando um utilizador do diretório ou o administrador permitir para a aplicação.
Depois de uma propriedade de extensão fica disponível num diretório, qualquer aplicação consented pode ler ou escrever um valor para essa propriedade de extensão para qualquer um dos objetos para que propriedade aplica-se de acordo com as permissões da aplicação no diretório. Os objetos para os quais se aplica a propriedade de extensão são especificados na propriedade targetObjects.
Um máximo de 100 valores de propriedade de extensão pode ser escrito num objeto específico num diretório. Por exemplo, assumindo que não existem outros valores de propriedade de extensão escritos qualquer utilizador num diretório, se uma aplicação escreve um valor de propriedade de extensão para user1, em seguida, os valores de 99 outras propriedades de extensão podem ser escritos user1 por essa aplicação ou outro aplicações com as permissões adequadas no diretório; No entanto, outros utilizadores no diretório continuarão a poder ter cópias de segurança para 100 valores de propriedade de extensão escritos aos mesmos.
Se uma aplicação tenta definir um valor para uma propriedade de extensão adicionais de um objeto para que extensão 100 valores de propriedade já foram definidos, Graph API devolve um 403 Proibido resposta com um código de erro de "Directory_ ResourceSizeExceeded"e a seguinte mensagem:"o tamanho do objeto excedeu o limite. Reduza o número de valores e repita o pedido de".
Se um programador anula o registo (eliminações) uma propriedade de extensão de uma aplicação, essa propriedade de extensão imediatamente torna-se inacessíveis no diretório de programador bem como nos diretórios para o qual a aplicação foi concedida consentimento.
Se a aplicação é removida do diretório de programador, todas as propriedades de extensão registado para essa aplicação imediatamente ficar inacessível no diretório do programador e diretórios nos quais essa aplicação concedeu consentimento.
Se uma aplicação multi-inquilino foi concedida consentimento num diretório e que a aplicação mais tarde é registo anulado com êxito (removidas) do diretório – por exemplo, de por um administrador através do portal de gestão do azure –, em seguida, quaisquer propriedades de extensão registadas no essa aplicação imediatamente ficar inacessível nesse diretório.
Um valor de propriedade de extensão tem de estar explicitamente definido como nulo para poder ser removida do objeto de diretório. Se um valor de propriedade de extensão está definido num objeto de diretório e de que a propriedade de extensão torna-se inacessíveis no diretório para qualquer um dos motivos citou acima, em seguida, a propriedade de extensão já não será visível no objeto desse diretório. Este irá, no entanto, ainda contagem contra o limite de valor de propriedade de extensão de 100 para esse objeto. Até que a disponibilidade de propriedade de extensão é restaurada – por exemplo, em alguns casos, por consenting para novamente a aplicação – o valor não serão acessível para leitura ou escrita.

Recursos adicionais

Referência de AD Graph API do Azure