Unidades administrativas (visualização) | Conceitos da API do Graph

Artigo
10/21/2021

Aplica-se a: API do Graph | Azure AD (Active Directory)

Visão geral e pré-requisitos

Uma Unidade Administrativa fornece um contêiner conceitual para objetos de diretório de Usuário e Grupo, permitindo que as permissões sejam delegadas em uma granularidade maior (ou seja: departamentais, regional etc.), funções administrativas no escopo da Unidade Administrativa. Este tópico fornece descrições das propriedades declaradas e propriedades de navegação pela entidade AdministrativeUnit, bem como as operações e funções que podem ser chamadas no recurso do OData administrativeUnits.

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.

A familiaridade com a configuração do aplicativo e autenticação do Azure AD também é necessária antes de usar a Visualização da Unidade Administrativa. Se você não estiver familiarizado com os conceitos associados à autenticação do Azure AD e/ou com as etapas de configuração necessárias para permitir que um aplicativo acesse seu locatário, examine Cenários de Autenticação do Azure AD, especificamente, a seção intitulada Noções Básicas Sobre o Registro de um Aplicativo no Azure AD, que está vinculado ao artigo mais detalhado Integrando Aplicativos com o Azure Active Directory.

Consulte o artigo principal API do Graph do Azure Active Directory em Azure.com e a seguinte lista de artigos da API do Graph para obter informações adicionais úteis e importantes antes de prosseguir para as seções a seguir:

Versão da API do Azure AD Graph

Importante: o recurso da Unidade Administrativa está disponível somente para Visualização no momento. Para usar recursos de visualização, certifique-se de definir o parâmetro de cadeia de caracteres de consulta de versão de api para "beta", ou seja: https://graph.windows.net/contoso.onmicrosoft.com/administrativeUnits?api-version=beta

Você pode criar e usar unidades administrativas somente se você habilitar o Active Directory Premium do Azure. Para obter mais informações, consulte Getting started with Azure Active Directory Premium (Introdução ao Azure Active Directory Premium)
Início Rápido para a API do Azure AD Graph no Azure.com
Visão geral das Operações da API do Graph
Opções de consultas, filtros e paginação com suporte

Namespace e herança

Namespace: Microsoft.DirectoryServices

Tipo de base: DirectoryObject

Propriedades

A entidade AdministrativeUnit dá suporte às seguintes propriedades:

Propriedades declaradas

Nome	Tipo	Create(POST)	Read(GET)	Update(PATCH)	Descrição
descrição	Edm.String	Opcional		Opcional	Uma descrição opcional para a unidade administrativa.
displayName	Edm.String	Necessária	Filtrável	Opcional	Nome de exibição da unidade administrativa.

Nome	Multiplicidade de origem	Para	Multiplicidade de destino	Descrição
membros	*	Usuário ou Grupo	*	Membros atribuídos à Unidade Administrativa, que podem ser Usuários ou Grupos. Herdado de DirectoryObject.
scopedAdministrators	*	ScopedRoleMembership	*	Administradores atribuídos para determinada Função, que têm o escopo para uma Unidade Administrativa.

Observação: embora a entidade DirectoryObject também dê suporte a outras propriedades de navegação, incluindo memberOf, owners e ownedObjects, essas propriedades não são válidas para a Unidade Administrativa. Se uma solicitação para qualquer uma dessas propriedades for enviada, uma resposta 400 Solicitação Incorreta será retornada com uma mensagem de erro correspondente.

Endereçamento

O endereçamento pode abranger uma coleção de unidades administrativas no diretório, uma unidade administrativa individual ou recursos relacionados disponíveis por meio de propriedades de navegação com suporte de uma unidade administrativa. Os exemplos na tabela usam o domínio de locatário para tratar o locatário. Para obter maneiras de abordar um locatário, consulte Addressing Entities and Operations in the Graph API (Endereçando Entidades e Operações na API do Graph).

Artefato	Fragmento de URL	Exemplo
Conjunto de recursos (todas as unidades administrativas)	/administrativeUnits	`https://graph.windows.net/contoso.onmicrosoft.com/administrativeUnits?api-version=beta`
Recurso único (por exemplo: uma unidade administrativa)	/administrativeUnits/{objectId}	`https://graph.windows.net/contoso.onmicrosoft.com/administrativeUnits/12345678-9abc-def0-1234-56789abcde?api-version=beta`
Recursos relacionados por meio de uma propriedade de Navegação	/administrativeUnits/{objectId}/$links/{property-name}	`https://graph.windows.net/contoso.onmicrosoft.com/administrativeUnits/12345678-9abc-def0-1234-56789abcde/$links/members?api-version=beta`

Observação: consulte a seção Propriedades de Navegação acima para obter a lista de propriedades de navegação válidas que podem ser usadas no lugar de {property-name}. Remova o segmento “$links” da parte do caminho de recursos do URI para retornar os objetos referenciados por uma propriedade de navegação, em vez dos links que levarão a eles. Você também pode endereçar com uma unidade administrativa usando objetos de diretório genéricos, substituindo “administrativeUnits” por “directoryObjects” na parte do caminho de recursos do URI.

Para obter informações mais abrangentes sobre como consultar objetos de diretório, consulte Azure AD Graph API Common Queries (Consultas Comuns da API do Graph do Azure AD) e Azure AD Graph API Differential Query (Consulta Diferencial da API do Graph do Azure AD).

Operações com Suporte – administrativeUnits

Esta seção define as operações com suporte em um conjunto de recursos de administrativeUnits. Como mencionado anteriormente, é importante examinar os tópicos na seção Visão Geral e Pré-requisitos para entender alguns dos conceitos básicos da API do Graph que se aplicam a todas as entidades, como formatação correta de URLs, abordagem de entidades e operações, uso de versões e muito mais.

Para cada uma das operações listadas abaixo:

A entidade de segurança que executa a operação deve estar em uma função de administrador que tem privilégios para modificar recursos de administrativeUnits usando solicitações PATCH, POST ou DELETE e privilégios para ler objetos usando solicitações GET.
Conforme apropriado, substitua as cadeias de caracteres de espaço reservado “contoso.onmicrosoft.com” pelo domínio do seu locatário do Azure Active Directory e {objectId} pela ID do tipo de recurso, conforme determinado na URL.
Cada solicitação deve incluir os seguintes cabeçalhos de Solicitação HTTP na tabela a seguir.

Cabeçalho de solicitação	Descrição
Authorization	Obrigatório. Um token de portador emitido pelo Active Directory do Azure. Consulte Authentication Scenarios for Azure AD (Cenários de Autenticação do Azure AD) para obter mais informações.
Content-Type	Obrigatório. O tipo de mídia do conteúdo do corpo da solicitação, por exemplo: application/json.
Content-Length	Obrigatório. O comprimento da solicitação em bytes.

As primeiras quatro operações listadas abaixo são usadas para gerenciar a criação, a recuperação, a atualização e a exclusão de entidades de AdministrativeUnit. As operações que seguem usam as propriedades de navegação members e scopedAdministrators para gerenciar os membros de Usuário/Grupo de AdminstrativeUnit, e o conjunto de administradores no escopo (via entidade ScopedRoleMembership) que tem controle administrativo da AdministrativeUnit, respectivamente.

Criar uma unidade administrativa

Usado para criar uma nova AdministrativeUnit.

Método HTTP	URI de solicitação
POST	`https://graph.windows.net/contoso.onmicrosoft.com/administrativeUnits?api-version=beta`

O corpo da solicitação especifica a propriedade necessária displayName e a opcional description:

{
  "displayName":"Central Region",
  "description":"Administrators responsible for the Central region."
}

Consulte a seção Referência de Resposta HTTP abaixo para obter definições de código de resposta. O corpo da resposta será semelhante ao mostrado abaixo.

{
   "odata.metadata":https://graph.windows.net/contoso.onmicrosoft.com/$metadata#directoryObjects/Microsoft.DirectoryServices.AdministrativeUnit/@Element",
   "odata.type":"Microsoft.DirectoryServices.AdministrativeUnit",
   "objectType":"AdministrativeUnit",
   "objectId":"ca1a80f3-ac25-429b-a1e9-0f1eb87cc30b",
   "deletionTimestamp":null,
   "displayName":"Central Region",
   "description":"Administrators responsible for the Central region."
}

Obter unidades administrativas

Usado para recuperar uma AdministrativeUnit específica por {objectId}, um subconjunto ao filtrar na propriedade displayName (consulte Supported Queries, Filters, and Paging Options in Azure AD Graph API (Consultas, Filtros e Opções de Paginação com Suporte na API do Graph do Azure AD)), ou a lista de todos os números disponíveis. Os exemplos de Solicitação/Resposta abaixo mostram consultas para uma unidade administrativa específica e para todas as unidades administrativas, respectivamente.

Método HTTP	URI de solicitação
GET	`https://graph.windows.net/contoso.onmicrosoft.com/administrativeUnits/{objectId}?api-version=beta`
GET	`https://graph.windows.net/contoso.onmicrosoft.com/administrativeUnits?api-version=beta`

Não há nenhum corpo de solicitação.

Consulte a seção Referência de Resposta HTTP abaixo para obter definições de código de resposta. O corpo da resposta será semelhante a um dos mostrados abaixo.

{
   "odata.metadata":https://graph.windows.net/contoso.onmicrosoft.com/$metadata#directoryObjects/Microsoft.DirectoryServices.AdministrativeUnit/@Element",
   "odata.type":"Microsoft.DirectoryServices.AdministrativeUnit",
   "objectType":"AdministrativeUnit",
   "objectId":"ca1a80f3-ac25-429b-a1e9-0f1eb87cc30b",
   "deletionTimestamp":null,
   "displayName":"Central Region",
   "description":"Administrators responsible for the Central region."
}

{
   "odata.metadata":https://graph.windows.net/contoso.onmicrosoft.com/$metadata#directoryObjects/Microsoft.DirectoryServices.AdministrativeUnit/",
   "value":
   [
      {
      "odata.type":"Microsoft.DirectoryServices.AdministrativeUnit",
      "objectType":"AdministrativeUnit",
      "objectId":"ca1a80f3-ac25-429b-a1e9-0f1eb87cc30b",
      "deletionTimestamp":null,
      "displayName":"Central Region",
      "description":"Administrators responsible for the Central region."
      },
      {
      "odata.type":"Microsoft.DirectoryServices.AdministrativeUnit",
      "objectType":"AdministrativeUnit",
      "objectId":"455b7304-b245-4d58-95c4-1797c32c80db",
      "deletionTimestamp":null,
      "displayName":"East Coast Region",
      "description":"East Coast Two"
      }
   ]
}

Atualizar uma unidade administrativa

Usado para atualizar uma ou mais das propriedades em uma AdministrativeUnit.

Método HTTP	URI de solicitação
PATCH	`https://graph.windows.net/contoso.onmicrosoft.com/administrativeUnits/{objectId}?api-version=beta`

O corpo da solicitação especifica uma ou ambas propriedades AdministrativeUnit:

{ 
  "displayName":"Central Region Administrators"
}

Consulte a seção Referência de Resposta HTTP abaixo para obter definições de código de resposta. Não há nenhuma resposta de OData no corpo da resposta.

Excluir uma unidade administrativa

Usado para excluir uma AdministrativeUnit, conforme especificado por {objectId}.

Método HTTP	URI de solicitação
DELETE	`https://graph.windows.net/contoso.onmicrosoft.com/administrativeUnits/{objectId}?api-version=beta`

Não há nenhum corpo de solicitação.

Consulte a seção Referência de Resposta HTTP abaixo para obter definições de código de resposta. Não há nenhuma resposta de OData no corpo da resposta.

As seguintes operações são implementadas por meio da propriedade de navegação membros, que fornece gerenciamento dos membros do grupo/usuário de uma AdminstrativeUnit. Lembre-se de que o segmento de recurso $links permite que você percorra ou modifique a associação (também conhecida como link) entre dois recursos, tais como entre um administrativeUnit e um recurso de User ou Group.

Adicionar membros a uma unidade administrativa

Usado para adicionar membros de recursos de usuário ou grupo a uma AdministrativeUnit.

Método HTTP	URI de solicitação
POST	`https://graph.windows.net/contoso.onmicrosoft.com/administrativeUnits/{objectId}/$links/members/?api-version=beta`

Nesse exemplo, o corpo da solicitação especifica a URL para o membro desejado que queremos adicionar a administrativeUnit, que é um recurso de usuários neste exemplo. Também é válido usar directoryObjects como o segmento de recurso de tipo no lugar de usuários, pois a entidade User é herdada da entidade DirectoryObject. O mesmo é verdadeiro ao usar o segmento de recursos de grupos.

{
  "url":" https://graph.windows.net/contoso.onmicrosoft.com/users/a1daa894-ff32-4839-bb6a-d7a4210fc96a"
}

Consulte a seção Referência de Resposta HTTP abaixo para obter definições de código de resposta. Não há nenhuma resposta de OData no corpo da resposta.

Obter membros de uma unidade administrativa

Usado para recuperar membros de recursos de usuário ou grupo de uma administrativeUnit. Observe que você pode recuperar membros usando o formato das operações GET listadas abaixo. A primeira retorna URL/link para os membros, a segunda retorna as propriedades para os membros. Em ambos os casos, o segmento de {memberObjectId} é opcional, dependendo se você quer que o conjunto de membros seja retornado ou um específico.

Método HTTP	URI de solicitação
GET	`https://graph.windows.net/contoso.onmicrosoft.com/administrativeUnits/{objectId}/$links/members/{memberObjectId}?api-version=beta`
GET	`https://graph.windows.net/contoso.onmicrosoft.com/administrativeUnits/{objectId}/members/{memberObjectId}?api-version=beta`

Não há nenhum corpo de solicitação.

Consulte a seção Referência de Resposta HTTP abaixo para obter definições de código de resposta. O primeiro exemplo abaixo mostra o corpo da resposta para uma operação usando o segmento $links para todos os membros (ou seja: {memberObjectId} não é especificado), em que há dois tipos de recursos, um Usuário e um Grupo. O segundo mostra a resposta para o mesmo exemplo, sem o segmento $links.

{
   "odata.metadata": "https://graph.windows.net/contoso.onmicrosoft.com/$metadata#directoryObjects/$links/members",
   "value":
   [
      {
      "url":"https://graph.windows.net/contoso.onmicrosoft.com/directoryObjects/a1daa894-ff32-4839-bb6a-d7a4210fc96a/Microsoft.DirectoryServices.User"
      },
      {
      "url":"https://graph.windows.net/contoso.onmicrosoft.com/directoryObjects/a0ab9340-2b20-4b3f-8672-bf1a2f141f91/Microsoft.DirectoryServices.Group"
      }
   ]
}

{
   "odata.metadata": "https://graph.windows.net/contoso.onmicrosoft.com/$metadata#directoryObjects",
   "value":
   [
      {
      "odata.type":"Microsoft.DirectoryServices.User",
      "objectType":"User",
      "objectId":"a1daa894-ff32-4839-bb6a-d7a4210fc96a",
      "deletionTimestamp":null,
      "acceptedAs":null,
      "acceptedOn":null,
      "accountEnabled":true,
      "alternativeSecurityIds":[],
      "alternativeSignInNames":[admin@contoso.com],
      "alternativeSignInNamesInfo":[],
      "appMetadata":null,
      "assignedLicenses":[],
      "assignedPlans":[],
      "city":"Redmond",
      "cloudSecurityIdentifier":"S-1-12-6-2715461780-1211760434-2765580987-1791561505",
      "companyName":null,
      "country":null,
      "creationType":null,
      "department":null,
      "dirSyncEnabled":null,
      "displayName":"Jon Doe",
      "extensionAttribute1":null,
      "extensionAttribute2":null,
      "extensionAttribute3":null,
      "extensionAttribute4":null,
      "extensionAttribute5":null,
      "extensionAttribute6":null,
      "extensionAttribute7":null,
      "extensionAttribute8":null,
      "extensionAttribute9":null,
      "extensionAttribute10":null,
      "extensionAttribute11":null,
      "extensionAttribute12":null,
      "extensionAttribute13":null,
      "extensionAttribute14":null,
      "extensionAttribute15":null,
      "facsimileTelephoneNumber":null,
      "givenName":"Jon",
      "immutableId":null,
      "invitedOn":null,
      "inviteReplyUrl":[],
      "inviteResources":[],
      "inviteTicket":[],
      "isCompromised":null,
      "jobTitle":null,
      "jrnlProxyAddress":null,
      "lastDirSyncTime":null,
      "mail":null,
      "mailNickname":"admin",
      "mobile":null,
      "netId":"100300008001EE6E",
      "onPremisesSecurityIdentifier":null,
      "otherMails":[jon@doe.com],
      "passwordPolicies":null,
      "passwordProfile":null,
      "physicalDeliveryOfficeName":null,
      "postalCode":"98052",
      "preferredLanguage":"en-US",
      "primarySMTPAddress":null,
      "provisionedPlans":[],
      "provisioningErrors":[],
      "proxyAddresses":[],
      "releaseTrack":null,
      "searchableDeviceKey":[],
      "selfServePasswordResetData":null,
      "sipProxyAddress":null,
      "smtpAddresses":[],
      "state":"WA",
      "streetAddress":
      "One Microsoft Way",
      "surname":"Doe",
      "telephoneNumber":"(123) 456-7890",
      "usageLocation":"US",
      "userPrincipalName":admin@constoso.com,
      "userState":null,
      "userStateChangedOn":null,
      "userType":"Member"      
      },
      { 
      "odata.type":"Microsoft.DirectoryServices.Group",
      "objectType":"Group",
      "objectId":"a0ab9340-2b20-4b3f-8672-bf1a2f141f91",
      "deletionTimestamp":null,
      "appMetadata":null,
      "cloudSecurityIdentifier":"S-1-12-6-2695598912-1262431008-448754310-2434733103",
      "description":null,
      "dirSyncEnabled":null,
      "displayName":"Group for users in Central Region Administrative Unit",
      "exchangeResources":[],
      "groupType":null,
      "isPublic":null,
      "lastDirSyncTime":null,
      "licenseAssignment":[],
      "mail":null,
      "mailEnabled":false,
      "mailNickname":"CentralUsers",
      "onPremisesSecurityIdentifier":null,
      "provisioningErrors":[],
      "proxyAddresses":[],
      "securityEnabled":true,
      "sharepointResources":[],
      "targetAddress":null,
      "wellKnownObject":null     
      }
   ]
}

Excluir membros de uma unidade administrativa

Usado para excluir membros de recursos de usuário ou grupo de um administrativeGroup. Como membros é uma propriedade de navegação com vários valores, você deve incluir o {objectId} do membro/link na URL da solicitação, o que você desejar excluir.

Método HTTP	URI de solicitação
DELETE	`https://graph.windows.net/contoso.onmicrosoft.com/administrativeUnits/{objectId}/$links/members/{objectId}?api-version=beta`

Não há nenhum corpo de solicitação.

Consulte a seção Referência de Resposta HTTP abaixo para obter definições de código de resposta. Não há nenhuma resposta de OData no corpo da resposta.

Os administradores são atribuídos a uma unidade administrativa, colocando-os em uma função que tem escopo para essa unidade administrativa. As operações restantes nesta seção são implementadas por meio da propriedade de navegação scopedAdministrators, que fornece gerenciamento dos administradores de conjunto que têm controle administrativo de uma AdministrativeUnit, por meio de uma função no escopo.

Adicionar um administrador com função no escopo para uma unidade administrativa

Usado para adicionar um administrador a uma função que terá escopo para uma administrativeUnit, via entidade ScopedRoleMembership e propriedade de navegação scopedAdministrators. Neste exemplo, a operação faz duas coisas:

Preenche um novo item ScopedRoleMembership (que NÃO é um recurso endereçável do OData), que estabelece uma relação entre uma AdministrativeUnit, uma DirectoryRole no escopo para a unidade administrativa e um Usuário administrador.
Estabelece um associação/link de propriedade de navegação entre a AdministrativeUnit e o novo item ScopedRoleMembership.

Método HTTP	URI de solicitação
POST	`https://graph.windows.net/contoso.onmicrosoft.com/administrativeUnits/{objectId}/scopedAdministrators?api-version=beta`

O corpo da solicitação especifica as seguintes propriedades da entidade ScopedRoleMembership:

roleObjectId – objectId do DirectoryRole desejado. Observação: no momento, somente as funções HelpDeskAdministrators e UserAccountAdministrator são válidas.
roleMemberInfo – uma estrutura que identifica Usuário administrativo: objectId – objectId do Usuário administrativo.
objectId – objectId do Usuário administrativo.

{
   "roleObjectId":"4bae1c93-ef8c-4907-83c8-1e1c1fd2e2c1",
   "roleMemberInfo":{
      "objectId":"a142bb2d-df81-4066-af91-f63e4aba9e5f"}
}

Consulte a seção Referência de Resposta HTTP abaixo para obter definições de código de resposta. O corpo da resposta será semelhante ao mostrado abaixo.

{
   "odata.metadata":https://graph.windows.net/contoso.onmicrosoft.com/$metadata#directoryObjects/Microsoft.DirectoryServices.AdministrativeUnit/@Element",
   "id":"kxyuS4zvB0mDyB4cH9Liwf2cwDwjVAJAhbgHDWCmP-Itu0Khgd9mQK-R9j5Kup5fU",
   "roleObjectId":"4bae1c93-ef8c-4907-83c8-1e1c1fd2e2c1",
   "administrativeUnitObjectId":"3cc09cfd-5423-4002-85b8-070d60a63fe2",
   "roleMemberInfo":{"objectId":"a142bb2d-df81-4066-af91-f63e4aba9e5f",
      "displayName":"Bryan",
      "userPrincipalName":BryanL@contoso.com
      }
}

Obter um administrador com função no escopo de uma unidade administrativa

Usado para obter a lista de administradores em funções com escopo para um recurso de administrativeUnit, como entidades ScopedRoleMembership. Observe que em ambos os casos, o segmento {scopedRoleMemberId} é opcional, dependendo se você quer o conjunto de membros ou um específico.

Método HTTP	URI de solicitação
GET	`https://graph.windows.net/contoso.onmicrosoft.com/administrativeUnits/{objectId}/scopedAdministrators/{scopedRoleMemberId}?api-version=beta`

Não há nenhum corpo de solicitação.

Consulte a seção Referência de Resposta HTTP abaixo para obter definições de código de resposta. O corpo da resposta abaixo é para uma consulta para todos os membros.

{ 
   "odata.metadata":https://graph.windows.net/contoso.onmicrosoft.com /$metadata#scopedRoleMemberships,
   "value":
   [
      {
      "id":"kxyuS4zvB0mDyB4cH9Liwf2cwDwjVAJAhbgHDWCmP-Itu0Khgd9mQK-R9j5Kup5fU",
      "roleObjectId":"4bae1c93-ef8c-4907-83c8-1e1c1fd2e2c1",
      "administrativeUnitObjectId":"3cc09cfd-5423-4002-85b8-070d60a63fe2",
      "roleMemberInfo":
         {
         "objectId":"a142bb2d-df81-4066-af91-f63e4aba9e5f",
         "displayName":"Bryan",
         "userPrincipalName":BryanL@contoso.com
         }
      }            
   ]
}

Excluir um administrador com função no escopo de uma unidade administrativa.

Usado para excluir uma ScopedRoleMembership de um recurso de administrativeUnit, especificado pelo segmento {scopedRoleMemberId}.

Método HTTP	URI de solicitação
DELETE	`https://graph.windows.net/contoso.onmicrosoft.com/administrativeUnits/{objectId}/scopedAdministrators/{scopedRoleMemberId}?api-version=beta`

Não há nenhum corpo de solicitação.

Consulte a seção Referência de Resposta HTTP abaixo para obter definições de código de resposta. Não há nenhuma resposta de OData no corpo da resposta.

Operações com Suporte – usuários e grupos

Esta seção define as operações com suporte recente em recursos de usuários e grupos, que oferecem suporte a recursos de administrativeUnit.

Você pode verificar a documentação completa de GA para as entidades User e Group e para operações em usuários e grupos.

Para cada uma das operações listadas abaixo:

A entidade de segurança que executa a operação deve ter privilégios para ler objetos usando solicitações GET.
Conforme apropriado, substitua as cadeias de caracteres de espaço reservado “contoso.onmicrosoft.com” pelo domínio do seu locatário do Azure Active Directory e {objectId} pela ID do tipo de recurso, conforme determinado na URL.

Cada solicitação deve incluir os seguintes cabeçalhos de Solicitação HTTP:

Cabeçalho de solicitação	Descrição
Authorization	Obrigatório. Um token de portador emitido pelo Active Directory do Azure. Consulte Authentication Scenarios for Azure AD (Cenários de Autenticação do Azure AD) para obter mais informações.
Content-Type	Obrigatório. O tipo de mídia do conteúdo do corpo da solicitação, por exemplo: application/json.
Content-Length	Obrigatório. O comprimento da solicitação em bytes.

Obter unidades administrativas ao qual um usuário ou um grupo pertence

A Visualização permite a recuperação da associação de administrativeUnits para recursos de usuários e grupos, por meio da propriedade de navegação memberOf na entidade DirectoryObject. Especifique o segmento de recurso de "usuários" para recuperar a associação para os recursos de usuários ou “grupos” para os recursos de grupos. Especifique o segmento de recurso de "$links" para recuperar URLs/links de recurso ou omita para recuperar as propriedades.

Método HTTP	URI de solicitação
GET	`https://graph.windows.net/contoso.onmicrosoft.com/users/{objectID}/$links/memberOf?api-version=beta`
GET	`https://graph.windows.net/contoso.onmicrosoft.com/users/{objectID}/memberOf?api-version=beta`
GET	`https://graph.windows.net/contoso.onmicrosoft.com/groups/{objectID}/$links/memberOf?api-version=beta`
GET	`https://graph.windows.net/contoso.onmicrosoft.com/groups/{objectID}/memberOf?api-version=beta`

Não há nenhum corpo de solicitação.

Consulte a seção Referência de Resposta HTTP abaixo para obter definições de código de resposta. O primeiro exemplo abaixo mostra o corpo da resposta para um recurso de usuários com o segmento de $links, o qual tem associação em dois tipos de recursos: DirectoryRole e AdministrativeUnit. O segundo mostra a resposta para o mesmo exemplo, sem o segmento $links.

{
   "odata.metadata": "https://graph.windows.net/contoso.onmicrosoft.com/$metadata#directoryObjects/$links/memberOf",
   "value":
   [
      {
      "url":"https://graph.windows.net/contoso.onmicrosoft.com/directoryObjects/cbf54c29-6184-484d-92d6-d6af32f896a2/Microsoft.DirectoryServices.DirectoryRole"
      },
      {
      "url":"https://graph.windows.net/contoso.onmicrosoft.com/directoryObjects/3cc09cfd-5423-4002-85b8-070d60a63fe2/Microsoft.DirectoryServices.AdministrativeUnit"
      }
   ]
}

{
   "odata.metadata": "https://graph.windows.net/contoso.onmicrosoft.com/$metadata#directoryObjects",
   "value":
   [
      {
      "odata.type":"Microsoft.DirectoryServices.DirectoryRole",
      "objectType":"Role",
      "objectId":"cbf54c29-6184-484d-92d6-d6af32f896a2",
      "deletionTimestamp":null,
      "cloudSecurityIdentifier":"S-1-12-6-3421850665-1213030788-2950092434-2727802930",
      "description":"Company Administrator role has full access to perform any operation in the company scope.",
      "displayName":"Company Administrator",
      "isSystem":true,
      "roleDisabled":false,
      "roleTemplateId":"62e90394-69f5-4237-9190-012177145e10"
      },
      {
      "odata.type":"Microsoft.DirectoryServices.AdministrativeUnit",
      "objectType":"AdministrativeUnit",
      "objectId":"3cc09cfd-5423-4002-85b8-070d60a63fe2",
      "deletionTimestamp":null,
      "displayName":"Central Region Administrators",
      "description":"Administrators responsible for the Central Region"
      }    
   ]  
}

Obter unidades administrativas das quais um usuário é um administrador

Usado para recuperar os recursos de adminstrativeUnits dos quais um usuário é um administrador, por meio da propriedade de navegação scopedAdministratorOf na entidade de Usuário. Observe que você pode usar qualquer forma das opções GET listadas abaixo. A primeira recupera URLs/link de recurso, a segunda retorna as propriedades.

Método HTTP	URI de solicitação
GET	`https://graph.windows.net/contoso.onmicrosoft.com/users/{objectId}/$links/scopedAdministratorOf?api-version=beta`
GET	`https://graph.windows.net/contoso.onmicrosoft.com/users/{objectId}/scopedAdministratorOf?api-version=beta`

Não há nenhum corpo de solicitação.

{
   "odata.metadata": "https://graph.windows.net/contoso.onmicrosoft.com/$metadata#directoryObjects/$links/scopedAdministratorOf",
   "value":
   [
      {
      "url":"https://graph.windows.net/contoso.onmicrosoft.com/scopedRoleMemberships/kxyuS4zvB0mDyB4cH9Liwf2cwDwjVAJAhbgHDWCmP-Itu0Khgd9mQK-R9j5Kup5fU"
      }
   ]
}```
```json
{
   "odata.metadata": "https://graph.windows.net/contoso.onmicrosoft.com/$metadata#scopedRoleMemberships",
   "value":
   [
      {
      "id":"kxyuS4zvB0mDyB4cH9Liwf2cwDwjVAJAhbgHDWCmP-Itu0Khgd9mQK-R9j5Kup5fU",
      "roleObjectId":"4bae1c93-ef8c-4907-83c8-1e1c1fd2e2c1",
      "administrativeUnitObjectId":"3cc09cfd-5423-4002-85b8-070d60a63fe2",
      "roleMemberInfo":
         {
         "objectId":"a142bb2d-df81-4066-af91-f63e4aba9e5f",
         "displayName":"Bryan",
         "userPrincipalName":BryanL@contoso.com
         }
      }
   ]  
}

Operações com Suporte – directoryRoles

Esta seção define as operações com suporte recente em recursos de directoryRoles, que oferecem suporte específico a recursos de administrativeUnits.

Você pode verificar a documentação completa de GA para obter mais informações sobre a entidade DirectoryRole e operações relacionadas****.

Para cada uma das operações listadas abaixo:

A entidade de segurança que executa a operação deve ter privilégios para ler objetos usando solicitações GET.
Conforme apropriado, substitua as cadeias de caracteres de espaço reservado “contoso.onmicrosoft.com” pelo domínio do seu locatário do Azure Active Directory e {objectId} pela ID do tipo de recurso, conforme determinado na URL.
Cada solicitação deve incluir os seguintes cabeçalhos de Solicitação HTTP: Request HeaderDescriptionAuthorizationRequired. Um token de portador emitido pelo Active Directory do Azure. Consulte Authentication Scenarios for Azure AD (Cenários de Autenticação do Azure AD) para obter mais informações.Content-TypeRequired. O tipo de mídia do conteúdo no corpo da solicitação, por exemplo: application/json.Content-LengthRequired. O comprimento da solicitação em bytes.

Cabeçalho de solicitação	Descrição
Authorization	Obrigatório. Um token de portador emitido pelo Active Directory do Azure. Consulte Authentication Scenarios for Azure AD (Cenários de Autenticação do Azure AD) para obter mais informações.
Content-Type	Obrigatório. O tipo de mídia do conteúdo do corpo da solicitação, por exemplo: application/json.
Content-Length	Obrigatório. O comprimento da solicitação em bytes.

Obtenha os administradores de unidade administrativa com escopo para uma função específica

Os administradores são atribuídos a uma unidade administrativa, colocando-os em uma função que tem escopo para essa unidade administrativa. Esta operação permite que você recupere essas "associações de função com escopo" para um administrador, como um conjunto de recursos scopedRoleMemberships. Observe que apenas uma função "HelpDeskAdministrators" ou "UserAccountAdministrator" {objectId} é válida. Observe também que o segmento de {scopedRoleMemberId} é opcional, dependendo se você deseja todos os recursos scopedRoleMembership para uma função específica ou um específico.

Método HTTP	URI de solicitação
GET	`https://graph.windows.net/contoso.onmicrosoft.com/directoryRoles/{objectId}/scopedAdministrators/{scopedRoleMemberId}?api-version=beta`

Não há nenhum corpo de solicitação.

Consulte a seção Referência de Resposta HTTP abaixo para obter definições de código de resposta. O corpo da resposta abaixo é para uma consulta para todos os administradores de uma determinada unidade administrativa, no escopo para a função de Administrador de Assistência Técnica.

{ 
   "odata.metadata":https://graph.windows.net/contoso.onmicrosoft.com /$metadata#scopedRoleMemberships,
   "value":[
   {
      "id":"kxyuS4zvB0mDyB4cH9Liwf2cwDwjVAJAhbgHDWCmP-Itu0Khgd9mQK-R9j5Kup5fU",
      "roleObjectId":"4bae1c93-ef8c-4907-83c8-1e1c1fd2e2c1",
      "administrativeUnitObjectId":"3cc09cfd-5423-4002-85b8-070d60a63fe2",
      "roleMemberInfo":
      {
         "objectId":"a142bb2d-df81-4066-af91-f63e4aba9e5f",
         "displayName":"Bryan",
         "userPrincipalName":BryanL@contoso.com
      }
   ]
}

Referência de resposta HTTP

Abaixo está a lista de possíveis códigos de resposta HTTP:

Código de status HTTP	Código de Erro OData	Descrição
200/OK	N/D	Resposta normal para uma consulta bem-sucedida. O corpo da resposta conterá os dados que correspondem aos filtros especificados nos parâmetros de consulta.
201/Criado	N/D	Resposta normal para uma operação POST/criar bem-sucedida. O corpo da resposta conterá os dados, conforme preenchido no novo recurso.
204/Sem Conteúdo	N/D	Resposta normal para uma operação bem-sucedida de PATCH/atualizar ou DELETE em um recurso ou POST em um recurso vinculado. O corpo da resposta não conterá uma resposta OData.
400/BadRequest	Request_BadRequest	Esta é uma mensagem de erro genérica para um cabeçalho, um parâmetro ou um corpo de solicitação inválido ou ausente. Você também verá esse erro se tentar adicionar um recurso vinculado que já existe.
401/Não Autorizado	AuthorizationError	Isso será exibido quando o usuário não estiver autorizado a exibir o conteúdo. Consulte o artigo principal do REST do AD Graph para obter detalhes adicionais sobre como proteger suas chamadas e como obter e especificar um token de acesso seguro.
404/Não Encontrado	Request_ResourceNotFound	Isso será exibido quando o recurso que você está tentando acessar não existir.
405/Método não permitido	Request_BadRequest	Isso será exibido quando você estiver tentando uma operação destinada a um recurso específico, mas não fornecer a ID de recurso correta na URL da solicitação.

Recursos adicionais

Para saber como gerenciar Unidades Administrativas usando o PowerShell, visite o artigo Gerenciamento de unidades administrativas no Azure AD – Visualização Pública.
Para obter informações sobre os tipos de dados primitivos do OData expostos pelo EDM, consulte Entity Data Model: Primitive Data Types (Modelo de Dados de Entidade: Tipos de dados primitivos).
Referência da API do Graph do Azure AD

Compartilhar via

Unidades administrativas (visualização) | Conceitos da API do Graph

Visão geral e pré-requisitos

Namespace e herança

Propriedades

Propriedades declaradas

Propriedades de navegação

Endereçamento

Operações com Suporte – administrativeUnits

Criar uma unidade administrativa

Obter unidades administrativas

Atualizar uma unidade administrativa

Excluir uma unidade administrativa

Adicionar membros a uma unidade administrativa

Obter membros de uma unidade administrativa

Excluir membros de uma unidade administrativa

Adicionar um administrador com função no escopo para uma unidade administrativa

Obter um administrador com função no escopo de uma unidade administrativa

Excluir um administrador com função no escopo de uma unidade administrativa.

Operações com Suporte – usuários e grupos

Obter unidades administrativas ao qual um usuário ou um grupo pertence

Obter unidades administrativas das quais um usuário é um administrador

Operações com Suporte – directoryRoles

Obtenha os administradores de unidade administrativa com escopo para uma função específica

Referência de resposta HTTP

Recursos adicionais

Recursos adicionais