logotipo azul

O Microsoft GraphAPI é uma ferramenta poderosa para ter. Não apenas podemos usá-lo para criar ferramentas para automatizar nossas cargas de trabalho, mas também podemos acessar novas funções anteriormente.

Neste artigo, aprenderemos como explorar e usar o Microsoft GraphAPI para Azure AD.

Pré-requisitos

Você deve atender a alguns pré-requisitos antes de começarmos. Antes de começar com as etapas descritas neste artigo, verifique se você atende ou tem o seguinte:

  • Um registro de aplicativo no AzureAD com as seguintes permissões GraphAPI:
    • Directory.Read.All
    • Directory.ReadWrite.All
  • ID do aplicativo (ID do cliente) e segredo do cliente para o Registro do aplicativo acima
  • O seu nome de inquilino
  • Um computador executando o PowerShell versão 5.1 ou superior

Com isso fora do caminho, vamos aprender a explorar a GraphAPI.

Leia a documentação

A Microsoft GraphAPI está bem documentada e o melhor local para começar a descobrir como usar uma nova função é iniciar na documentação de referência da API do Microsoft Graph.

Isso especifica como usar uma função específica e quais permissões você precisa para usá-la. Atualmente, existem duas versões do GraphAPI: v1.0 e a API beta. Eles podem parecer idênticos no início, mas a API beta contém muitas funções novas que ainda não foram lançadas. Esteja ciente de que as funções na API beta estão sujeitas a alterações a qualquer momento.

Permissões

As permissões são uma parte importante da exploração e uso das permissões da API do Graph - felizmente todas as permissões necessárias para executar uma determinada ação são especificadas na documentação de referência dessa função.

A captura de tela a seguir mostra a permissão necessária para usar o getDirectoryObject função. E como você o acessará como um aplicativo, precisará do Directory.ReadAll permissão.

Você precisa da permissão Directory.ReadAll para usar a função getDirectoryObject.

Agora que você tem o básico, vamos começar solicitando um token de acesso - um segredo temporário que usaremos para acessar a API do Microsoft Graph.

Solicitando um token de acesso

O token de acesso é um segredo que você pode solicitar com nossa identificação de cliente e segredo de cliente. É esse token que você deve nas solicitações para o GraphAPI.

Para solicitar um token de acesso, você precisa se autorizar contra o terminal oauth2 do inquilino postando seu ID do aplicativo e seu segredo de aplicativo.

Edite o seguinte script, substituindo AppId, AppSecret e nome do inquilino, e execute-o no PowerShell para solicitar um token de acesso:

 Add-Type -AssemblyName System.Web $ AppId = 'CHANGEME' $ AppSecret = 'CHANGEME' $ Scope = "https://graph.microsoft.com/.default" $ TenantName = "CHANGEME.onmicrosoft.com" $ Url = "https://login.microsoftonline.com/$TenantName/oauth2/v2.0/token" $ Body = @ {   client_id = $ AppId client_secret = $ AppSecret scope = $ Scope grant_type = 'client_credentials' } $ PostSplat = @ {     ContentType = 'application / x-www-form-urlencoded'     Método = 'POST'     Corpo = $ Corpo     Uri = $ Url } # Solicite o token! $ Request = Invoke-RestMethod @PostSplat 

Agora, se você der uma olhada no $ Request variável, você pode ver que ele contém nosso token de acesso, bem como o tipo e o tempo de expiração.

PS51> $ Request token_type expires_in ext_expires_in access_token ---------- ---------- -------------- ------------ Portador 3599 3599 eyJ ............... 

o expira em está em segundos, o que significa que você precisa solicitar um novo token dentro de uma hora ou ele deixará de funcionar.

Vamos salvar o token de acesso em uma variável para uso futuro e começar a fazer solicitações para o GraphApi:

PS51> $ AccessToken = $ Request.access_token 

Sua primeira solicitação GraphAPI

Chegou a hora do seu primeiro pedido de gráfico! Os pedidos mais simples para começar são os que utilizam HTTP GET. Os comandos GET são apenas para buscar informações. Portanto, você não precisa se preocupar em estragar nada.

Começaremos com uma solicitação simples listando os domínios vinculados ao nosso inquilino. E lembre-se - leia a documentação. Todas as informações sobre como usar as funções GraphAPI estão na documentação.

Você deve ter notado na documentação do Listar domínios comando que você pode chamar usando HTTP GET - o método padrão ao usar Invoke-RestMethod:

Você pode chamar um comando List Domains usando HTTP GET.

Com essas informações, você pode começar a construir a solicitação. Para isso, precisamos criar um Cabeçalho da Autorização que contém "Portador ”E use isso para fazer uma solicitação GET para o URL na figura acima:

$ Cabeçalhos = @ {     Autorização = "Portador $ AccessToken" } $ Uri = "https://graph.microsoft.com/v1.0/domains" $ Result = Invoke-RestMethod -Headers $ Headers -Uri $ Uri 

Agora você tem a lista de domínios no diretório $ Resultado variável, mas tentando gerar o valor da variável $ Resultado A variável resultará neste:

PS51> $ Resultado @ valor odata.context -------------- -----  {@ {authenticationType = Gerenciado; AvailabilityStatus =; id = contoso.com; isAdminManaged = True; isD .. 

O resultado da consulta geralmente está no valor propriedade do resultado. Você pode obter o resultado inteiro apenas exibindo essa propriedade:

PS51> $ Result.value authenticationType: gerenciado status de disponibilidade : id: contoso.com isAdminManaged: True isDefault: True isInitial: False isRoot: True isVerified: True supportServices: {Email, Intune} Estado : passwordValidityPeriodInDays: 2147483647 passwordNotificationWindowInDays: 14 authenticationType: gerenciado status de disponibilidade : ID: contoso.onmicrosoft.com isAdminManaged: True isDefault: False isInitial: True isRoot: True isVerified: True supportServices: {Email, OfficeCommunicationsOnline} Estado : passwordValidityPeriodInDays: 2147483647 passwordNotificationWindowInDays: 14 

Agora que você aprendeu o básico sobre como obter informações com o GraphAPI, é hora de aprender a usar filtros.

Usando filtros

É ótimo poder buscar todos os dados disponíveis. E, embora possa funcionar, é terrivelmente ineficaz. Uma boa prática é solicitar apenas os dados necessários. Para conseguir isso no GraphAPI, podemos usar filtros.

Um bom candidato para experimentar os filtros é buscar usuários. Eles têm muitos nomes de atributos comuns no Active Directory local, e você geralmente tem pelo menos alguns deles.

O URI para buscar todos os usuários é * https: //graph.microsoft.com/v1.0/users*, mas queremos filtrar essa solicitação. Você pode fazer isso adicionando o $ filter = parâmetro para o URI.

Um filtro (geralmente) consiste em operador de propriedade e um valor como este:

operador de propriedade 'value' 

Se agora você deseja buscar todos os usuários com o nome dado "John", o seguinte URI deve ser usado:

https://graph.microsoft.com/v1.0/users?$filter=givenName eq 'John' 

Portanto, se você deseja usar o PowerShell para fazer essa solicitação, o código deve ter a seguinte aparência:

$ Uri = "https://graph.microsoft.com/v1.0/users?`$filter=givenName eq 'John'" $ Result = Invoke-RestMethod -Headers $ Headers -Uri $ Uri 

Observe o backtick antes $ filter, Para escapar do cifrão, o PowerShell o interpretaria como uma variável.

Dê uma olhada na propriedade value e você verá todos os usuários com um determinadoName "John" no Azure Active Directory:

PS51> $ Result.value businessPhones: {5554012} displayName: John Doe givenName: John Titulo do trabalho : mail: jdoe@contoso.com celular : localização do escritório : preferidoLanguage: en sobrenome: Doe userPrincipalName: jdoe@contoso.com Identidade: 7fd22087-ec0a-47a1-91fb-0a7d8e6f0c 

'EQ' não é o único operador, você não possui (ne), corresponde, contém menos / maior que (lt / gt) e muito mais. Fora do escopo deste artigo, mais informações sobre operadores estão disponíveis na documentação. Também existe uma documentação mais extensa sobre as diferentes propriedades do filtro na documentação da propriedade sobre cada tipo de objeto.

Criando um usuário

Agora que você entendeu o básico, vamos realizar uma operação de gravação e criar um usuário. Para isso, você precisa saber como construir os dados e onde colocá-los. Você pode ver um exemplo de como fazer isso acessando a documentação da API do Microsoft Graph e olhando para "Criar usuário":

Execute uma operação de gravação e crie um usuário.

Você pode ver que precisa enviar os dados como uma solicitação POST e que o tipo de conteúdo deve ser de application / json. Você também pode ver uma representação JSON dos dados - o objetivo aqui é criar um objeto do PowerShell que crie esse JSON quando ConvertTo-Json é usado nele.

Vamos tentar:

$ Body = (PSCustomObject) @ {     accountEnabled = $ True     displayName = "Jane Doe"     mailNickname = "janedoe"     userPrincipalName = "jane.doe@automativity.com"     passwordProfile = @ {         forceChangePasswordNextSignIn = $ True         password = "Hunter221!"     } } 

Corrida $ Corpo | ConvertTo-Json resultará em um JSON semelhante ao exibido na documentação. O que resta agora é convertê-lo em JSON e colocá-lo no URI GraphAPI com o tipo de conteúdo certo:

$ Body = (PSCustomObject) @ {     accountEnabled = $ True     displayName = "Jane Doe"     mailNickname = "janedoe"     userPrincipalName = "jane.doe@contoso.com"     passwordProfile = @ {         forceChangePasswordNextSignIn = $ True         password = "Hunter221!"     } } $ BodyJson = $ Corpo | ConvertTo-Json $ Uri = "https://graph.microsoft.com/v1.0/users" Invoke-RestMethod -Uri $ Uri -Headers $ Headers -Method POST -ContentType application / json -Body $ BodyJson 

Se agora você acessa o Console do Active Directory do Azure e dá uma olhada, encontrará o usuário recém-criado:

O usuário recém-criado no Console do Azure Active Directory.

Você criou seu primeiro usuário usando o GraphAPI!

Conclusão

O Microsoft GraphAPI é uma ferramenta poderosa e permitirá automatizar ainda mais o seu ambiente. E não apenas no que diz respeito ao Azure Active Directory - mas também para a maioria dos serviços SaaS que a Microsoft oferece.

Considerando também o movimento "sem servidor" usando o Azure Functions ou o AWS Lambda em um evento, é possível criar funções minimalistas e controladas por eventos para automatizar o máximo possível em seu ambiente. Tudo sem a necessidade de incluir grandes bibliotecas em suas funções.

Adicione ao Google Notícias
Neste artigo
  1. Pré-requisitos
  2. Leia a documentação
  3. Solicitando um token de acesso
  4. Sua primeira solicitação GraphAPI
  5. Usando filtros
  6. Criando um usuário
  7. Conclusão