Criar aplicativos Python com o Microsoft Graph e autenticação somente aplicativo
Este tutorial ensina como criar um aplicativo de console python que usa o microsoft API do Graph para acessar dados usando autenticação somente aplicativo. A autenticação somente aplicativo é uma boa opção para serviços em segundo plano ou aplicativos que precisam acessar dados para todos os usuários de uma organização.
Observação
Para saber como usar o Microsoft Graph para acessar dados em nome de um usuário, consulte este tutorial de autenticação de usuário (delegado).
Neste tutorial, você vai:
Dica
Como alternativa a seguir este tutorial, você pode baixar ou clonar o repositório GitHub e seguir as instruções no README para registrar um aplicativo e configurar o projeto.
Pré-requisitos
Antes de iniciar este tutorial, você deve ter Python e pip instalados em seu computador de desenvolvimento.
Você também deve ter uma conta de trabalho ou de estudante da Microsoft com a função Administrador global. Se você não tiver um locatário do Microsoft 365, poderá se qualificar para um por meio do Programa de Desenvolvedores do Microsoft 365; para obter detalhes, confira as perguntas frequentes. Como alternativa, você pode se inscrever para uma avaliação gratuita de 1 mês ou comprar um plano do Microsoft 365.
Observação
Este tutorial foi escrito com Python versão 3.10.4 e pip versão 20.0.2. As etapas neste guia podem funcionar com outras versões, mas isso não foi testado.
Registrar o aplicativo no portal
Neste exercício, você registrará um novo aplicativo no Azure Active Directory para habilitar a autenticação somente aplicativo. Você pode registrar um aplicativo usando o centro de administração do Azure Active Directory ou usando o SDK do Microsoft Graph PowerShell.
Registrar aplicativo para autenticação somente aplicativo
Nesta seção, você registrará um aplicativo que dá suporte à autenticação somente aplicativo usando o fluxo de credenciais do cliente.
Abra um navegador e navegue até o centro de administração do Azure Active Directory e faça logon usando uma conta Administrador global.
Selecione Azure Active Directory na navegação esquerda e selecione Registros de aplicativos em Gerenciar.
Selecione Novo registro. Insira um nome para seu aplicativo, por exemplo,
Graph App-Only Auth Tutorial
.Defina tipos de conta com suporte apenas para contas neste diretório organizacional.
Deixe o URI de Redirecionamento vazio.
Selecione Registrar. Na página Visão geral do aplicativo, copie o valor da ID do Aplicativo (cliente) e da ID do Diretório (locatário) e salve-os, você precisará desses valores na próxima etapa.
Selecione Permissões de API em Gerenciar.
Remova a permissão padrão User.Read em Permissões configuradas selecionando as reticências (...) em sua linha e selecionando Remover permissão.
Selecione Adicionar uma permissão e, em seguida, Microsoft Graph.
Selecione Permissões de aplicativos.
Selecione User.Read.All e, em seguida, selecione Adicionar permissões.
Selecione Conceder consentimento do administrador para...e selecione Sim para fornecer o consentimento do administrador para a permissão selecionada.
Selecione Certificados e segredos em Gerenciar e selecione Novo segredo do cliente.
Insira uma descrição, escolha uma duração e selecione Adicionar.
Copie o segredo da coluna Valor , você precisará dele nas próximas etapas.
Importante
Este segredo do cliente nunca é mostrado novamente, portanto, certifique-se de copiá-lo agora.
Observação
Observe que, ao contrário das etapas ao se registrar para autenticação do usuário, nesta seção você configurou as permissões do Microsoft Graph no registro do aplicativo. Isso ocorre porque a auth somente aplicativo usa o fluxo de credenciais do cliente, o que exige que as permissões sejam configuradas no registro do aplicativo. Consulte O escopo .default para obter detalhes.
Criar um aplicativo de console do Python
Comece criando um novo arquivo Python.
Crie um novo arquivo chamado main.py e adicione o código a seguir.
print ('Hello world!')
Salve o arquivo e use o comando a seguir para executar o arquivo.
python3 main.py
Se funcionar, o aplicativo deverá gerar
Hello world!
.
Instalar dependências
Antes de seguir em frente, adicione algumas dependências adicionais que você usará posteriormente.
- Biblioteca de clientes do Azure Identity para Python para autenticar o usuário e adquirir tokens de acesso.
- SDK do Microsoft Graph para Python (versão prévia) para fazer chamadas para o Microsoft Graph.
Execute os comandos a seguir na CLI para instalar as dependências.
python3 -m pip install azure-identity
python3 -m pip install msgraph-sdk
Carregar configurações do aplicativo
Nesta seção, você adicionará os detalhes do registro do aplicativo ao projeto.
Crie um arquivo no mesmo diretório que main.py chamado config.cfg e adicione o código a seguir.
[azure] clientId = YOUR_CLIENT_ID_HERE clientSecret = YOUR_CLIENT_SECRET_HERE tenantId = YOUR_TENANT_ID_HERE
Atualize os valores de acordo com a tabela a seguir.
Configuração Valor clientId
A ID do cliente do registro do aplicativo clientSecret
O segredo do cliente do registro do aplicativo tenantId
A ID do locatário da sua organização Dica
Opcionalmente, você pode definir esses valores em um arquivo separado chamado config.dev.cfg.
Design do aplicativo
Nesta seção, você criará um menu simples baseado em console.
Crie um novo arquivo chamado graph.py e adicione o código a seguir a esse arquivo.
# Temporary placeholder class Graph: def __init__(self, config): self.settings = config
Esse código é um espaço reservado. Você implementará a
Graph
classe na próxima seção.Abra main.py e substitua todo o conteúdo pelo código a seguir.
import asyncio import configparser from msgraph.generated.models.o_data_errors.o_data_error import ODataError from graph import Graph async def main(): print('Python Graph App-Only Tutorial\n') # Load settings config = configparser.ConfigParser() config.read(['config.cfg', 'config.dev.cfg']) azure_settings = config['azure'] graph: Graph = Graph(azure_settings) choice = -1 while choice != 0: print('Please choose one of the following options:') print('0. Exit') print('1. Display access token') print('2. List users') print('3. Make a Graph call') try: choice = int(input()) except ValueError: choice = -1 try: if choice == 0: print('Goodbye...') elif choice == 1: await display_access_token(graph) elif choice == 2: await list_users(graph) elif choice == 3: await make_graph_call(graph) else: print('Invalid choice!\n') except ODataError as odata_error: print('Error:') if odata_error.error: print(odata_error.error.code, odata_error.error.message)
Adicione os seguintes métodos de espaço reservado no final do arquivo. Você os implementará em etapas posteriores.
async def display_access_token(graph: Graph): # TODO return async def list_users(graph: Graph): # TODO return async def make_graph_call(graph: Graph): # TODO return
Adicione a linha a seguir para chamar
main
no final do arquivo.# Run main asyncio.run(main())
Isso implementa um menu básico e lê a escolha do usuário na linha de comando.
Adicionar autenticação somente aplicativo
Nesta seção, você adicionará a autenticação somente aplicativo ao aplicativo. Isso é necessário para obter o token de acesso OAuth necessário para chamar o Microsoft Graph. Nesta etapa, você integrará a biblioteca de clientes do Azure Identity para Python ao aplicativo e configurará a autenticação para o SDK do Microsoft Graph para Python (versão prévia).
A biblioteca de Identidade do Azure fornece várias classes que implementam fluxos de TokenCredential
token OAuth2. O SDK do Microsoft Graph usa essas classes para autenticar chamadas para o Microsoft Graph.
Configurar o cliente graph para autenticação somente aplicativo
Nesta seção, você usará a ClientSecretCredential
classe para solicitar um token de acesso usando o fluxo de credenciais do cliente.
Abra graph.py e substitua todo o conteúdo pelo código a seguir.
from configparser import SectionProxy from azure.identity.aio import ClientSecretCredential from msgraph import GraphServiceClient from msgraph.generated.users.users_request_builder import UsersRequestBuilder class Graph: settings: SectionProxy client_credential: ClientSecretCredential app_client: GraphServiceClient def __init__(self, config: SectionProxy): self.settings = config client_id = self.settings['clientId'] tenant_id = self.settings['tenantId'] client_secret = self.settings['clientSecret'] self.client_credential = ClientSecretCredential(tenant_id, client_id, client_secret) self.app_client = GraphServiceClient(self.client_credential) # type: ignore
Esse código declara duas propriedades privadas, um
ClientSecretCredential
objeto e umGraphServiceClient
objeto. A__init__
função cria uma nova instância deClientSecretCredential
, em seguida, usa essa instância para criar uma nova instância deGraphServiceClient
. Sempre que uma chamada de API for feita ao Microsoft Graph por meio doapp_client
, ela usará a credencial fornecida para obter um token de acesso.Adicione a função a seguir ao graph.py.
async def get_app_only_token(self): graph_scope = 'https://graph.microsoft.com/.default' access_token = await self.client_credential.get_token(graph_scope) return access_token.token
Substitua a função vazia
display_access_token
no main.py pelo seguinte.async def display_access_token(graph: Graph): token = await graph.get_app_only_token() print('App-only token:', token, '\n')
Crie e execute o aplicativo. Insira
1
quando solicitado para uma opção. O aplicativo exibe um token de acesso.Python Graph App-Only Tutorial Please choose one of the following options: 0. Exit 1. Display access token 2. List users 3. Make a Graph call 1 App-only token: eyJ0eXAiOiJKV1QiLCJub25jZSI6IlVDTzRYOWtKYlNLVjVkRzJGenJqd2xvVUcwWS...
Dica
Somente para fins de validação e depuração, você pode decodificar tokens de acesso somente aplicativo usando o analisador de token online da Microsoft em https://jwt.ms. Isso pode ser útil se você encontrar erros de token ao chamar o Microsoft Graph. Por exemplo, verificar se a
role
declaração no token contém os escopos de permissão esperados do Microsoft Graph.
Listar usuários
Nesta seção, você adicionará a capacidade de listar todos os usuários em seu Azure Active Directory usando autenticação somente aplicativo.
Adicione a função a seguir ao graph.py.
async def get_users(self): query_params = UsersRequestBuilder.UsersRequestBuilderGetQueryParameters( # Only request specific properties select = ['displayName', 'id', 'mail'], # Get at most 25 results top = 25, # Sort by display name orderby= ['displayName'] ) request_config = UsersRequestBuilder.UsersRequestBuilderGetRequestConfiguration( query_parameters=query_params ) users = await self.app_client.users.get(request_configuration=request_config) return users
Substitua a função vazia
list_users
no main.py pelo seguinte.async def list_users(graph: Graph): users_page = await graph.get_users() # Output each users's details if users_page and users_page.value: for user in users_page.value: print('User:', user.display_name) print(' ID:', user.id) print(' Email:', user.mail) # If @odata.nextLink is present more_available = users_page.odata_next_link is not None print('\nMore users available?', more_available, '\n')
Execute o aplicativo e escolha a opção 2 para listar usuários.
Please choose one of the following options: 0. Exit 1. Display access token 2. List users 3. Make a Graph call 2 User: Adele Vance ID: 05fb57bf-2653-4396-846d-2f210a91d9cf Email: AdeleV@contoso.com User: Alex Wilber ID: a36fe267-a437-4d24-b39e-7344774d606c Email: AlexW@contoso.com User: Allan Deyoung ID: 54cebbaa-2c56-47ec-b878-c8ff309746b0 Email: AllanD@contoso.com User: Bianca Pisani ID: 9a7dcbd0-72f0-48a9-a9fa-03cd46641d49 Email: None User: Brian Johnson (TAILSPIN) ID: a8989e40-be57-4c2e-bf0b-7cdc471e9cc4 Email: BrianJ@contoso.com ... More users available? True
Código explicado
Considere o código na get_users
função.
- Ele obtém uma coleção de usuários
- Ele usa para solicitar propriedades específicas
$select
- Ele usa para limitar o número de usuários retornados
$top
- Ele usa
$orderBy
para classificar a resposta
Opcional: adicionar seu próprio código
Nesta seção, você adicionará seus próprios recursos do Microsoft Graph ao aplicativo. Isso pode ser um snippet de código da documentação do Microsoft Graph ou do Graph Explorer ou código que você criou. Esta seção é opcional.
Atualizar o aplicativo
Adicione a função a seguir ao graph.py.
async def make_graph_call(self): # INSERT YOUR CODE HERE return
Substitua a função vazia
list_inbox
no main.py pelo seguinte.async def make_graph_call(graph: Graph): await graph.make_graph_call()
Escolher uma API
Encontre uma API no Microsoft Graph que você gostaria de experimentar. Por exemplo, a API criar eventos . Você pode usar um dos exemplos na documentação da API ou criar sua própria solicitação de API.
Configurar as permissões
Verifique a seção Permissões da documentação de referência da API escolhida para ver quais métodos de autenticação têm suporte. Algumas APIs não dão suporte somente a aplicativos ou contas pessoais da Microsoft, por exemplo.
- Para chamar uma API com autenticação de usuário (se a API dá suporte à autenticação do usuário (delegada), consulte o tutorial de autenticação do usuário (delegado ).
- Para chamar uma API com autenticação somente aplicativo (se a API dá suporte a ela), adicione o escopo de permissão necessário no centro de administração Azure AD.
Adicionar seu código
Copie seu código na make_graph_call
função em graph.py.
Parabéns!
Você concluiu o tutorial do Python Microsoft Graph. Agora que você tem um aplicativo de trabalho que chama Microsoft Graph, você pode experimentar e adicionar novos recursos.
- Saiba como usar a autenticação de usuário (delegada) com o SDK do Microsoft Graph Python.
- Visite a visão geral do Microsoft Graph para ver todos os dados que você pode acessar com o Microsoft Graph.
Exemplos de Python
Tem algum problema com essa seção? Se tiver, envie seus comentários para que possamos melhorar esta seção.