Criar aplicativos Python com o Microsoft Graph
Este tutorial ensina como criar um aplicativo de console python que usa o Microsoft API do Graph.
Importante
O Microsoft Graph Core Python Client Library está atualmente em versão prévia e não deve ser usado em produção. Durante esse período, espera-se que ocorram alterações interruptivas. Este tutorial foi escrito com a versão 0.2.2.
Dica
Se você preferir apenas baixar o tutorial concluído, poderá baixar ou clonar o GitHub repositório.
Pré-requisitos
Antes de iniciar este tutorial, você deve ter o Python e o pip instalados em seu computador de desenvolvimento.
Você também deve ter uma conta microsoft pessoal com uma caixa de correio no Outlook.com ou uma conta corporativa ou de estudante da Microsoft. Se você não tiver uma conta da Microsoft, há algumas opções para obter uma conta gratuita:
- Você pode se inscrever para uma nova conta pessoal da Microsoft.
- Você pode se inscrever no Microsoft 365 Developer Program para obter uma assinatura Microsoft 365 assinatura gratuita.
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 do usuário. Você pode registrar um aplicativo usando o Azure Active Directory de administração ou usando o SDK do Microsoft Graph PowerShell.
Importante
O Microsoft Graph Core Python Client Library está atualmente em versão prévia e não deve ser usado em produção. Durante esse período, espera-se que ocorram alterações interruptivas. Este tutorial foi escrito com a versão 0.2.2.
Registrar aplicativo para autenticação de usuário
Nesta seção, você registrará um aplicativo que dá suporte à autenticação de usuário usando o fluxo de código do dispositivo.
Abra um navegador, navegue até o centro de administração do Azure Active Directory e faça logon usando uma conta pessoal (também conhecida como conta da Microsoft) ou Conta Corporativa ou de Estudante.
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,
Python Graph Tutorial.Defina os tipos de conta com suporte conforme desejado. As opções são:
Opção Who pode entrar? Contas apenas neste diretório organizacional Somente usuários em sua Microsoft 365 organização Contas em qualquer diretório organizacional Usuários em qualquer Microsoft 365 (contas corporativas ou de estudante) Contas em qualquer diretório organizacional... e contas pessoais da Microsoft Usuários em qualquer organização Microsoft 365 (contas corporativas ou de estudante) e contas pessoais da Microsoft 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 salve-o. Você precisará dele na próxima etapa. Se você escolheu Contas neste diretório organizacional apenas para tipos de conta com suporte, copie também a ID do Diretório (locatário) e salve-a.
Selecione Autenticação em Gerenciar. Localize a seção Configurações avançadas e altere a alternância Permitir fluxos do cliente público para Sim e, em seguida, escolha Salvar.
Observação
Observe que você não configurou nenhuma permissão do Microsoft Graph no registro do aplicativo. Isso ocorre porque o exemplo usará o consentimento dinâmico para solicitar permissões específicas para autenticação do usuário.
Criar um aplicativo de console do Python
Comece criando um novo arquivo Python.
Importante
O Microsoft Graph Core Python Client Library está atualmente em versão prévia e não deve ser usado em produção. Durante esse período, espera-se que ocorram alterações interruptivas. Este tutorial foi escrito com a versão 0.2.2.
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.pySe funcionar, o aplicativo deverá gerar saída
Hello world!.
Instalar dependências
Antes de continuar, adicione algumas dependências adicionais que você usará posteriormente.
- Biblioteca de clientes de Identidade do Azure para Python para autenticar o usuário e adquirir tokens de acesso.
- Microsoft Graph Core Python Client Library (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-core
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 config.cfg nomeado e adicione o código a seguir.
Atualize os valores de acordo com a tabela a seguir.
Configuração Valor clientIdA ID do cliente do registro do aplicativo authTenantSe você escolheu a opção para permitir que apenas os usuários em sua organização se conectem, altere esse valor para sua ID de locatário. Caso contrário, deixe como common.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.
Abra main.py e substitua todo o conteúdo pelo código a seguir.
Adicione os métodos de espaço reservado a seguir ao final do arquivo. Você os implementará em etapas posteriores.
def greet_user(graph: Graph): # TODO return def display_access_token(graph: Graph): # TODO return 1 def list_inbox(graph: Graph): # TODO return def send_mail(graph: Graph): # TODO return def list_users(graph: Graph): # TODO return def make_graph_call(graph: Graph): # TODO returnAdicione a linha a seguir para
mainchamar no final do arquivo.# Run main main()
Isso implementa um menu básico e lê a escolha do usuário na linha de comando.
Adicionar autenticação de usuário
Nesta seção, você estenderá o aplicativo do exercício anterior para dar suporte à autenticação com Azure AD. 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 de Identidade do Azure para Python ao aplicativo e configurará a autenticação para a Biblioteca de Clientes Python do Microsoft Graph Core (versão prévia).
Importante
O Microsoft Graph Core Python Client Library está atualmente em versão prévia e não deve ser usado em produção. Durante esse período, espera-se que ocorram alterações interruptivas. Este tutorial foi escrito com a versão 0.2.2.
A biblioteca de identidade do Azure fornece várias TokenCredential classes que implementam fluxos de token OAuth2. A biblioteca de Graph microsoft usa essas classes para autenticar chamadas para o Microsoft Graph. Neste exemplo, usaremos as classes a TokenCredential seguir.
DeviceCodeCredentialimplementa o fluxo de código do dispositivo para autenticação do usuário.ClientSecretCredentialimplementa o fluxo de credenciais do cliente para autenticação somente de aplicativo. Você usará essa classe nas seções opcionais somente de aplicativo.
Configurar Graph cliente para autenticação de usuário
Nesta seção, você usará a classe para DeviceCodeCredential solicitar um token de acesso usando o fluxo de código do dispositivo.
Crie um novo arquivo chamado graph.py e adicione o código a seguir a esse arquivo.
Esse código declara duas propriedades privadas, um
DeviceCodeCredentialobjeto e umGraphClientobjeto. Ainitialize_graph_for_user_authfunção cria uma nova instância deDeviceCodeCredential, em seguida, usa essa instância para criar uma nova instância deGraphClient. Sempre que uma chamada à API for feita ao Microsoft Graphuser_client, ela usará a credencial fornecida para obter um token de acesso.Adicione a função a seguir graph.py.
Substitua a função
display_access_tokenvazia main.py pelo seguinte.Compile e execute o aplicativo. Insira
1quando for solicitada uma opção. O aplicativo exibe uma URL e um código do dispositivo.Python Graph Tutorial Please choose one of the following options: 0. Exit 1. Display access token 2. List my inbox 3. Send mail 4. List users (requires app-only) 5. Make a Graph call 1 To sign in, use a web browser to open the page https://microsoft.com/devicelogin and enter the code RB2RUD56D to authenticate.Abra um navegador e navegue até a URL exibida. Insira o código fornecido e entre.
Importante
Lembre-se de todas as contas Microsoft 365 existentes que estão conectadas ao seu navegador ao navegar até
https://microsoft.com/devicelogin. Use recursos do navegador, como perfis, modo de convidado ou modo privado, para garantir que você se autentique como a conta que pretende usar para teste.Depois de concluído, retorne ao aplicativo para ver o token de acesso.
Dica
Somente para fins de validação e depuração , você pode decodificar tokens de acesso do usuário (somente para contas corporativas ou de estudante) 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 declaração
scpno token contém os escopos de permissão Graph Microsoft esperados.
Obter usuário
Nesta seção, você incorporará o microsoft Graph no aplicativo. Para esse aplicativo, você usará a Biblioteca de Clientes do Microsoft Graph Core Python (versão prévia) para fazer chamadas ao Microsoft Graph.
Importante
O Microsoft Graph Core Python Client Library está atualmente em versão prévia e não deve ser usado em produção. Durante esse período, espera-se que ocorram alterações interruptivas. Este tutorial foi escrito com a versão 0.2.2.
Adicione a função a seguir graph.py.
Substitua a função
greet_uservazia main.py pelo seguinte.
Se você executar o aplicativo agora, depois de fazer logon, o aplicativo receberá você pelo nome.
Hello, Megan Bowen!
Email: MeganB@contoso.com
Código explicado
Considere o código na get_user função. São apenas algumas linhas, mas há alguns detalhes importantes a serem notado.
Acessando 'eu'
A função cria uma solicitação para a API Obter usuário . Essa API pode ser acessada de duas maneiras:
GET /me
GET /users/{user-id}
Nesse caso, o código chamará o ponto de extremidade GET /me da API. Esse é um método de atalho para obter o usuário autenticado sem saber sua ID de usuário.
Observação
Como o GET /me ponto de extremidade da API obtém o usuário autenticado, ele só está disponível para aplicativos que usam autenticação de usuário. Os aplicativos de autenticação somente de aplicativo não podem acessar esse ponto de extremidade.
Solicitando propriedades específicas
A função usa o $select de consulta para especificar o conjunto de propriedades de que precisa. O Microsoft Graph retornará apenas as propriedades solicitadas na resposta.
Caixa de entrada de lista
Nesta seção, você adicionará a capacidade de listar mensagens na caixa de entrada de email do usuário.
Importante
O Microsoft Graph Core Python Client Library está atualmente em versão prévia e não deve ser usado em produção. Durante esse período, espera-se que ocorram alterações interruptivas. Este tutorial foi escrito com a versão 0.2.2.
Adicione a função a seguir graph.py.
Substitua a função
list_inboxvazia main.py pelo seguinte.Execute o aplicativo, entre e escolha a opção 2 para listar sua caixa de entrada.
Please choose one of the following options: 0. Exit 1. Display access token 2. List my inbox 3. Send mail 4. List users (requires app-only) 5. Make a Graph call 2 Message: Updates from Ask HR and other communities From: Contoso Demo on Yammer Status: Read Received: 2022-04-26T19:19:05Z Message: Employee Initiative Thoughts From: Patti Fernandez Status: Read Received: 2022-04-25T19:43:57Z Message: Voice Mail (11 seconds) From: Alex Wilber Status: Unread Received: 2022-04-22T19:43:23Z Message: Our Spring Blog Update From: Alex Wilber Status: Unread Received: 2022-04-19T22:19:02Z Message: Atlanta Flight Reservation From: Alex Wilber Status: Unread Received: 2022-04-19T15:15:56Z Message: Atlanta Trip Itinerary - down time From: Alex Wilber Status: Unread Received: 2022-04-18T14:24:16Z ... More messages available? True
Código explicado
Considere o código na get_inbox função.
Acessando pastas de email conhecidas
A função cria uma solicitação para a API listar mensagens . Como ele inclui o segmento /mailFolders/inbox na URL de solicitação, a API retornará apenas mensagens na pasta de email solicitada. Nesse caso, como a caixa de entrada é uma pasta padrão e conhecida dentro da caixa de correio de um usuário, ela é acessível por meio de seu nome conhecido. As pastas não padrão são acessadas da mesma maneira, substituindo o nome conhecido pela propriedade de ID da pasta de email. Para obter detalhes sobre os nomes de pasta conhecidos disponíveis, consulte o tipo de recurso mailFolder.
Acessando uma coleção
Ao contrário get_user da função da seção anterior, que retorna um único objeto, esse método retorna uma coleção de mensagens. A maioria das APIs no Microsoft Graph que retornam uma coleção não retorna todos os resultados disponíveis em uma única resposta. Em vez disso, eles usam a paginação para retornar uma parte dos resultados, fornecendo um método para os clientes solicitarem a próxima "página".
Tamanhos de página padrão
As APIs que usam paginação implementam um tamanho de página padrão. Para mensagens, o valor padrão é 10. Os clientes podem solicitar mais (ou menos) usando o parâmetro $top consulta.
Observação
O valor passado é $top um limite superior, não um número explícito. A API retorna um número de mensagens até o valor especificado.
Obtendo páginas subsequentes
Se houver mais resultados disponíveis no servidor, @odata.nextLink as respostas da coleção incluirão uma propriedade com uma URL de API para acessar a próxima página. Se essa propriedade estiver presente, haverá mais resultados disponíveis.
Classificando coleções
A função usa o $orderby de consulta para solicitar resultados classificados pelo momento em que a mensagem é recebida (receivedDateTime propriedade). Ele inclui a palavra-chave DESC para que as mensagens recebidas mais recentemente sejam listadas primeiro.
Enviar email
Nesta seção, você adicionará a capacidade de enviar uma mensagem de email como o usuário autenticado.
Importante
O Microsoft Graph Core Python Client Library está atualmente em versão prévia e não deve ser usado em produção. Durante esse período, espera-se que ocorram alterações interruptivas. Este tutorial foi escrito com a versão 0.2.2.
Adicione a função a seguir graph.py.
Substitua a função
send_mailvazia main.py pelo seguinte.Execute o aplicativo, entre e escolha a opção 3 para enviar um email para si mesmo.
Please choose one of the following options: 0. Exit 1. Display access token 2. List my inbox 3. Send mail 4. List users (requires app-only) 5. Make a Graph call 3 Mail sent.Observação
Se você estiver testando com um locatário de desenvolvedor do Microsoft 365 Developer Program, o email enviado poderá não ser entregue e você poderá receber um relatório de não entrega. Se isso acontecer com você, entre em contato com o suporte por meio do Centro de administração do Microsoft 365.
Código explicado
Considere o código na send_mail função.
Enviar email
A função cria uma solicitação para a API enviar email .
Criando objetos
Ao contrário das chamadas anteriores ao Microsoft Graph que somente leem dados, essa chamada cria dados. Para fazer isso com a biblioteca de clientes, crie um dicionário que representa o conteúdo da solicitação, defina as propriedades desejadas e, em seguida, envie-o na chamada à API. Como a chamada está enviando dados, o post método é usado em vez de get.
Opcional: configurar a autenticação somente de aplicativo
Nesta seção, você atualizará o registro do aplicativo da seção anterior para dar suporte à autenticação somente de aplicativo. A autenticação somente de aplicativo é uma boa opção para serviços em segundo plano e também há algumas APIs que dão suporte apenas à autenticação somente de aplicativo. Você só precisará concluir esta seção se pretende usar as partes somente de aplicativo deste tutorial. Caso contrário, você pode pular com segurança para a próxima etapa.
Importante
O Microsoft Graph Core Python Client Library está atualmente em versão prévia e não deve ser usado em produção. Durante esse período, espera-se que ocorram alterações interruptivas. Este tutorial foi escrito com a versão 0.2.2.
Importante
As etapas nesta seção exigem uma conta corporativa/de estudante com a Administrador global função.
Abra o registro do aplicativo na seção anterior no Azure AD de administração.
Selecione Permissões de API em Gerenciar.
Remova a permissão User.Read padrão 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 aplicativo.
Selecione User.Read.All e, em seguida, selecione Adicionar permissões.
Selecione Conceder consentimento do administrador para... e, em seguida, selecione Sim para fornecer consentimento do administrador para a permissão selecionada.
Selecione Certificados e segredos em Gerenciar e, em seguida, 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 autenticação somente de 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.
Opcional: adicionar autenticação somente de aplicativo
Nesta seção, você adicionará a autenticação somente de aplicativo ao aplicativo. Esta seção é opcional e requer a conclusão de Opcional: configurar a autenticação somente de aplicativo. Essas etapas só podem ser concluídas com uma conta corporativa ou de estudante.
Importante
O Microsoft Graph Core Python Client Library está atualmente em versão prévia e não deve ser usado em produção. Durante esse período, espera-se que ocorram alterações interruptivas. Este tutorial foi escrito com a versão 0.2.2.
Configurar Graph cliente para autenticação somente de aplicativo
Nesta seção, você usará a classe para ClientSecretCredential solicitar um token de acesso usando o fluxo de credenciais do cliente.
Atualize os valores em config.cfg (ou config.dev.cfg) de acordo com a tabela a seguir.
Configuração Valor tenantIdID do locatário da sua organização clientSecretO segredo do cliente gerado na etapa anterior Adicione a função a seguir graph.py.
Opcional: listar usuários
Nesta seção, você adicionará a capacidade de listar todos os usuários em seu Azure Active Directory usando a autenticação somente de aplicativo. Esta seção é opcional e requer a conclusão de Opcional: configurar a autenticação somente de aplicativo e Opcional: adicionar autenticação somente de aplicativo. Essas etapas só podem ser concluídas com uma conta corporativa ou de estudante.
Importante
O Microsoft Graph Core Python Client Library está atualmente em versão prévia e não deve ser usado em produção. Durante esse período, espera-se que ocorram alterações interruptivas. Este tutorial foi escrito com a versão 0.2.2.
Adicione a função a seguir graph.py.
Substitua a função
list_inboxvazia main.py pelo seguinte.Execute o aplicativo, entre e escolha a opção 4 para listar usuários.
Please choose one of the following options: 0. Exit 1. Display access token 2. List my inbox 3. Send mail 4. List users (requires app-only) 5. Make a Graph call 4 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. É muito semelhante ao código em get_inbox:
- Ele obtém uma coleção de usuários
- Ele usa para
$selectsolicitar propriedades específicas - Ele usa
$toppara limitar o número de usuários retornados - Ele usa
$orderBypara classificar a resposta
A principal diferença é que esse código usa o app_client, não o user_client. Ambos os clientes usam a mesma sintaxe e construtores de solicitação, mas foram configurados com credenciais diferentes.
Opcional: adicionar seu próprio código
Nesta seção, você adicionará seus próprios recursos Graph Microsoft ao aplicativo. Pode ser um snippet de código da documentação do Microsoft Graph ou Graph Explorer ou código que você criou. Esta seção é opcional.
Importante
O Microsoft Graph Core Python Client Library está atualmente em versão prévia e não deve ser usado em produção. Durante esse período, espera-se que ocorram alterações interruptivas. Este tutorial foi escrito com a versão 0.2.2.
Atualizar o aplicativo
Adicione a função a seguir graph.py.
Substitua a função
list_inboxvazia main.py pelo seguinte.
Escolher uma API
Encontre uma API no Microsoft Graph que você gostaria de experimentar. Por exemplo, a API criar evento . 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 der suporte à autenticação de usuário (delegada), adicione o escopo de permissão necessário em config.cfg.
- Para chamar uma API com autenticação somente de aplicativo (se a API der suporte a ela), adicione o escopo de permissão necessário no Azure AD de administração.
Adicionar seu código
Copie seu código para a make_graph_call função em graph.py.
Parabéns!
Você concluiu o tutorial do Python microsoft Graph. Agora que você tem um aplicativo funcional que chama o Microsoft Graph, você pode experimentar e adicionar novos recursos. Visite a Visão geral do Microsoft Graph para ver todos os dados que você pode acessar com o Microsoft Graph.
Exemplos do Python
Tem algum problema com essa seção? Se tiver, envie seus comentários para que possamos melhorar esta seção.