Criar aplicativos PHP com o Microsoft Graph

Artigo
Developer (Iniciante)
29 minutos para concluir

Este tutorial ensina-o a criar uma aplicação de consola PHP que utiliza a Microsoft Graph API para aceder a dados em nome de um utilizador.

Observação

Para saber como utilizar o Microsoft Graph para aceder a dados através da autenticação apenas de aplicações, veja este tutorial de autenticação apenas de aplicações.

Neste tutorial, você vai:

Dica

Como alternativa a seguir este tutorial, pode transferir o código concluído através da ferramenta de início rápido , que automatiza o registo e a configuração de aplicações. O código transferido funciona sem quaisquer modificações necessárias.

Também pode transferir ou clonar o repositório do GitHub e seguir as instruções no README para registar uma aplicação e configurar o projeto.

Pré-requisitos

Antes de iniciar este tutorial, deve ter o PHP e o Compositor instalados no seu computador de desenvolvimento.

Também deve ter uma conta escolar ou profissional da Microsoft com uma caixa de correio do Exchange Online. Se não tiver um inquilino do Microsoft 365, poderá qualificar-se para um através do Programa para Programadores do Microsoft 365; para obter detalhes, veja as FAQ. Em alternativa, pode inscrever-se numa avaliação gratuita de um mês ou comprar um plano do Microsoft 365.

Observação

Este tutorial foi escrito com a versão PHP 8.1.5 e Composer versão 2.3.5. Os passos neste guia podem funcionar com outras versões, mas isso não foi testado.

Registrar o aplicativo no portal

28 minutos restantes

Neste exercício, irá registar uma nova aplicação no Azure Active Directory para ativar a autenticação de utilizadores. Pode registar uma aplicação através do centro de administração do Microsoft Entra ou através do SDK do PowerShell do Microsoft Graph.

Registar aplicação para autenticação de utilizador

Nesta secção, irá registar uma aplicação que suporta a autenticação de utilizador através do fluxo de código do dispositivo.

Centro de administração do Microsoft Entra
PowerShell

Abra um browser e navegue para o centro de administração do Microsoft Entra e inicie sessão com uma conta de Administrador global.
Selecione Microsoft Entra ID no painel de navegação esquerdo, expanda Identidade, expanda Aplicações e, em seguida, selecione Registos de aplicações.
Selecione Novo registro. Introduza um nome para a sua aplicação, por exemplo, Graph User Auth Tutorial.

Defina Tipos de conta suportados conforme pretendido. As opções são:

Opção	Quem pode iniciar sessão?
Contas apenas neste diretório organizacional	Apenas utilizadores na sua organização do Microsoft 365
Contas em qualquer diretório organizacional	Utilizadores em qualquer organização do Microsoft 365 (contas escolares ou profissionais)
Contas em qualquer diretório organizacional... e contas Microsoft pessoais	Utilizadores em qualquer organização do Microsoft 365 (contas escolares ou profissionais) e contas Microsoft pessoais

Deixe o URI de Redirecionamento vazio.
Selecione Registrar. Na página Descrição Geral da aplicação, copie o valor do ID da Aplicação (cliente) e guarde-o, irá precisar dele no próximo passo. Se escolheu Contas neste diretório organizacional apenas para Tipos de conta suportados, copie também o ID do Diretório (inquilino) e guarde-o.
Selecione Autenticação em Gerenciar. Localize a secção Definições avançadas e altere o botão de alternar Permitir fluxos de cliente públicos para Sim e, em seguida, selecione Guardar.

Para utilizar o PowerShell, precisará do SDK do PowerShell do Microsoft Graph. Se não o tiver, veja Instalar o SDK do PowerShell do Microsoft Graph para obter instruções de instalação.

Importante

O script do PowerShell requer uma conta escolar/profissional com o Administrador da aplicação, o administrador da aplicação na cloud ou a função de Administrador global. Se a sua conta tiver a função de Programador de aplicações, pode registar-se no centro de administração do Microsoft Entra.

Crie um novo ficheiro com o nomeRegisterAppForUserAuth.ps1 e adicione o seguinte código.

param(
  [Parameter(Mandatory=$true,
  HelpMessage="The friendly name of the app registration")]
  [String]
  $AppName,

  [Parameter(Mandatory=$false,
  HelpMessage="The sign in audience for the app")]
  [ValidateSet("AzureADMyOrg", "AzureADMultipleOrgs", `
  "AzureADandPersonalMicrosoftAccount", "PersonalMicrosoftAccount")]
  [String]
  $SignInAudience = "AzureADandPersonalMicrosoftAccount",

  [Parameter(Mandatory=$false)]
  [Switch]
  $StayConnected = $false
)

# Tenant to use in authentication.
# See https://learn.microsoft.com/azure/active-directory/develop/v2-oauth2-device-code#device-authorization-request
$authTenant = switch ($SignInAudience)
{
  "AzureADMyOrg" { "tenantId" }
  "AzureADMultipleOrgs" { "organizations" }
  "AzureADandPersonalMicrosoftAccount" { "common" }
  "PersonalMicrosoftAccount" { "consumers" }
  default { "invalid" }
}

if ($authTenant -eq "invalid")
{
  Write-Host -ForegroundColor Red "Invalid sign in audience:" $SignInAudience
  Exit
}

# Requires an admin
Connect-MgGraph -Scopes "Application.ReadWrite.All User.Read" -UseDeviceAuthentication -ErrorAction Stop

# Get context for access to tenant ID
$context = Get-MgContext -ErrorAction Stop

if ($authTenant -eq "tenantId")
{
  $authTenant = $context.TenantId
}

# Create app registration
$appRegistration = New-MgApplication -DisplayName $AppName -SignInAudience $SignInAudience `
 -IsFallbackPublicClient -ErrorAction Stop
Write-Host -ForegroundColor Cyan "App registration created with app ID" $appRegistration.AppId

# Create corresponding service principal
if ($SignInAudience -ne "PersonalMicrosoftAccount")
{
  New-MgServicePrincipal -AppId $appRegistration.AppId -ErrorAction SilentlyContinue `
   -ErrorVariable SPError | Out-Null
  if ($SPError)
  {
    Write-Host -ForegroundColor Red "A service principal for the app could not be created."
    Write-Host -ForegroundColor Red $SPError
    Exit
  }

  Write-Host -ForegroundColor Cyan "Service principal created"
}

Write-Host
Write-Host -ForegroundColor Green "SUCCESS"
Write-Host -ForegroundColor Cyan -NoNewline "Client ID: "
Write-Host -ForegroundColor Yellow $appRegistration.AppId
Write-Host -ForegroundColor Cyan -NoNewline "Auth tenant: "
Write-Host -ForegroundColor Yellow $authTenant

if ($StayConnected -eq $false)
{
  Disconnect-MgGraph | Out-Null
  Write-Host "Disconnected from Microsoft Graph"
}
else
{
  Write-Host
  Write-Host -ForegroundColor Yellow `
   "The connection to Microsoft Graph is still active. To disconnect, use Disconnect-MgGraph"
}

Salve o arquivo.
Abra o PowerShell e altere o diretório atual para a localização de RegisterAppForUserAuth.ps1.

Execute o seguinte comando, substituindo <audience-value> pelo valor pretendido (veja a tabela abaixo).

.\RegisterAppForUserAuth.ps1 -AppName "Graph User Auth Tutorial" -SignInAudience <audience-value>

Valor SignInAudience	Quem pode iniciar sessão?
`AzureADMyOrg`	Apenas utilizadores na sua organização do Microsoft 365
`AzureADMultipleOrgs`	Utilizadores em qualquer organização do Microsoft 365 (contas escolares ou profissionais)
`AzureADandPersonalMicrosoftAccount`	Utilizadores em qualquer organização do Microsoft 365 (contas escolares ou profissionais) e contas Microsoft pessoais
`PersonalMicrosoftAccount`	Apenas contas Microsoft pessoais

Siga o pedido para abrir https://microsoft.com/devicelogin num browser, introduza o código fornecido e conclua o processo de autenticação.
Copie os valores do ID de Cliente e do inquilino de Autenticação a partir da saída do script. Irá precisar destes valores no próximo passo.
```
SUCCESS
Client ID: 2fb1652f-a9a0-4db9-b220-b224b8d9d38b
Auth tenant: common
```

Observação

Repare que não configurou quaisquer permissões do Microsoft Graph no registo de aplicações. Isto deve-se ao facto de o exemplo utilizar o consentimento dinâmico para pedir permissões específicas para a autenticação do utilizador.

Criar uma aplicação de consola PHP

25 minutos restantes

Comece por inicializar um novo projeto Compositor. Abra a interface de linha de comandos (CLI) num diretório onde pretende criar o projeto. Execute o seguinte comando:

composer init

Responda às instruções. Pode aceitar as predefinições para a maioria das perguntas, mas responder n ao seguinte:

Would you like to define your dependencies (require) interactively [yes]? n
Would you like to define your dev dependencies (require-dev) interactively [yes]? n
Add PSR-4 autoload mapping? Maps namespace "Microsoft\Graphtutorial" to the entered relative path. [src/, n to skip]: n

Instalar dependências

Antes de continuar, adicione algumas dependências adicionais que irá utilizar mais tarde.

SDK do Microsoft Graph para PHP para fazer chamadas para o Microsoft Graph.
vlucas/phpdotenv para ler variáveis de ambiente a partir de ficheiros .env.

Execute o seguinte comando na CLI para instalar as dependências.

composer require microsoft/microsoft-graph vlucas/phpdotenv

Carregar as definições da aplicação

Nesta secção, irá adicionar os detalhes do registo da aplicação ao projeto.

Crie um ficheiro no diretório de raiz do projeto com o nome .env e adicione o seguinte código.

CLIENT_ID=YOUR_CLIENT_ID_HERE
TENANT_ID=common
GRAPH_USER_SCOPES='user.read mail.read mail.send'

Atualize os valores de acordo com a tabela seguinte.

Configuração	Valor
`CLIENT_ID`	O ID de cliente do registo de aplicações
`TENANT_ID`	Se escolheu a opção para permitir que apenas os utilizadores na sua organização iniciem sessão, altere este valor para o ID de inquilino. Caso contrário, deixe como `common`.

Importante

Se estiver a utilizar o controlo de origem, como o git, agora seria uma boa altura para excluir o ficheiro .env do controlo de origem para evitar fugas inadvertidas do ID da aplicação.

Design do aplicativo

Nesta secção, irá criar um menu simples baseado na consola.

Crie um ficheiro no diretório de raiz do projeto com o nome main.php. Adicione as etiquetas PHP de abertura e fecho.
```
<?php
?>
```

Adicione o seguinte código entre as etiquetas PHP.

// Enable loading of Composer dependencies
require_once realpath(__DIR__ . '/vendor/autoload.php');
require_once 'GraphHelper.php';

print('PHP Graph Tutorial'.PHP_EOL.PHP_EOL);

// Load .env file
$dotenv = Dotenv\Dotenv::createImmutable(__DIR__);
$dotenv->load();
$dotenv->required(['CLIENT_ID', 'TENANT_ID', 'GRAPH_USER_SCOPES']);

initializeGraph();

greetUser();

$choice = -1;

while ($choice != 0) {
    echo('Please choose one of the following options:'.PHP_EOL);
    echo('0. Exit'.PHP_EOL);
    echo('1. Display access token'.PHP_EOL);
    echo('2. List my inbox'.PHP_EOL);
    echo('3. Send mail'.PHP_EOL);
    echo('4. Make a Graph call'.PHP_EOL);

    $choice = (int)readline('');

    switch ($choice) {
        case 1:
            displayAccessToken();
            break;
        case 2:
            listInbox();
            break;
        case 3:
            sendMail();
            break;
        case 4:
            makeGraphCall();
            break;
        case 0:
        default:
            print('Goodbye...'.PHP_EOL);
    }
}

Adicione os seguintes métodos de marcador de posição no final do ficheiro antes da etiqueta PHP de fecho. Irá implementá-los em passos posteriores.

function initializeGraph(): void {
    // TODO
}

function greetUser(): void {
    // TODO
}

function displayAccessToken(): void {
    // TODO
}

function listInbox(): void {
    // TODO
}

function sendMail(): void {
    // TODO
}

function makeGraphCall(): void {
    // TODO
}

Esta ação implementa um menu básico e lê a escolha do utilizador a partir da linha de comandos.

Adicionar autenticação de utilizador

20 minutos restantes

Nesta secção, irá expandir a aplicação do exercício anterior para suportar a autenticação com o Azure AD. Isto é necessário para obter o token de acesso OAuth necessário para chamar o Microsoft Graph.

Criar fornecedor de tokens de acesso

O SDK do Microsoft Graph inclui fornecedores de autenticação baseados no cliente OAuth2 da Liga PHP. No entanto, para este tutorial, irá utilizar o fluxo de código do dispositivo para obter tokens de acesso. Os fornecedores de autenticação incluídos não implementam este fluxo, pelo que irá implementar um fornecedor de tokens de acesso personalizado.

Crie um novo ficheiro no diretório de raiz do projeto com o nome DeviceCodeTokenProvider.php. Adicione o código a seguir.

<?php
// Copyright (c) Microsoft Corporation. All rights reserved.
// Licensed under the MIT license.

use GuzzleHttp\Client;
use Http\Promise\FulfilledPromise;
use Http\Promise\Promise;
use Http\Promise\RejectedPromise;
use Microsoft\Kiota\Abstractions\Authentication\AccessTokenProvider;
use Microsoft\Kiota\Abstractions\Authentication\AllowedHostsValidator;

class DeviceCodeTokenProvider implements AccessTokenProvider {

    private string $clientId;
    private string $tenantId;
    private string $scopes;
    private AllowedHostsValidator $allowedHostsValidator;
    private string $accessToken;
    private Client $tokenClient;

    public function __construct(string $clientId, string $tenantId, string $scopes) {
        $this->clientId = $clientId;
        $this->tenantId = $tenantId;
        $this->scopes = $scopes;
        $this->allowedHostsValidator = new AllowedHostsValidator();
        $this->allowedHostsValidator->setAllowedHosts([
            "graph.microsoft.com",
            "graph.microsoft.us",
            "dod-graph.microsoft.us",
            "graph.microsoft.de",
            "microsoftgraph.chinacloudapi.cn"
        ]);
        $this->tokenClient = new Client();
    }

    public function getAuthorizationTokenAsync(string $url, array $additionalAuthenticationContext = []): Promise {
        $parsedUrl = parse_url($url);
        $scheme = $parsedUrl["scheme"] ?? null;

        if ($scheme !== 'https' || !$this->getAllowedHostsValidator()->isUrlHostValid($url)) {
            return new FulfilledPromise(null);
        }

        // If we already have a user token, just return it
        // Tokens are valid for one hour, after that it needs to be refreshed
        if (isset($this->accessToken)) {
            return new FulfilledPromise($this->accessToken);
        }

        // https://learn.microsoft.com/azure/active-directory/develop/v2-oauth2-device-code
        $deviceCodeRequestUrl = 'https://login.microsoftonline.com/'.$this->tenantId.'/oauth2/v2.0/devicecode';
        $tokenRequestUrl = 'https://login.microsoftonline.com/'.$this->tenantId.'/oauth2/v2.0/token';

        // First POST to /devicecode
        $deviceCodeResponse = json_decode($this->tokenClient->post($deviceCodeRequestUrl, [
            'form_params' => [
                'client_id' => $this->clientId,
                'scope' => $this->scopes
            ]
        ])->getBody()->getContents());

        // Display the user prompt
        print($deviceCodeResponse->message.PHP_EOL);

        // Response also indicates how often to poll for completion
        // And gives a device code to send in the polling requests
        $interval = (int)$deviceCodeResponse->interval;
        $device_code = $deviceCodeResponse->device_code;

        // Do polling - if attempt times out the token endpoint
        // returns an error
        while (true) {
            sleep($interval);

            // POST to the /token endpoint
            $tokenResponse = $this->tokenClient->post($tokenRequestUrl, [
                'form_params' => [
                    'client_id' => $this->clientId,
                    'grant_type' => 'urn:ietf:params:oauth:grant-type:device_code',
                    'device_code' => $device_code
                ],
                // These options are needed to enable getting
                // the response body from a 4xx response
                'http_errors' => false,
                'curl' => [
                    CURLOPT_FAILONERROR => false
                ]
            ]);

            if ($tokenResponse->getStatusCode() == 200) {
                // Return the access_token
                $responseBody = json_decode($tokenResponse->getBody()->getContents());
                $this->accessToken = $responseBody->access_token;
                return new FulfilledPromise($responseBody->access_token);
            } else if ($tokenResponse->getStatusCode() == 400) {
                // Check the error in the response body
                $responseBody = json_decode($tokenResponse->getBody()->getContents());
                if (isset($responseBody->error)) {
                    $error = $responseBody->error;
                    // authorization_pending means we should keep polling
                    if (strcmp($error, 'authorization_pending') != 0) {
                        return new RejectedPromise(
                            new Exception('Token endpoint returned '.$error, 100));
                    }
                }
            }
        }
    }

    public function getAllowedHostsValidator(): AllowedHostsValidator {
        return $this->allowedHostsValidator;
    }
}
?>

Configurar o cliente do Graph para autenticação de utilizador

Nesta secção, irá utilizar a DeviceCodeTokenProvider classe para pedir um token de acesso através do fluxo de código do dispositivo.

Crie um novo ficheiro no diretório de raiz do projeto com o nome GraphHelper.php. Adicione o código a seguir.
```
<?php
class GraphHelper {
}
?>
```

Adicione as seguintes using instruções nas etiquetas PHP.

use Microsoft\Graph\Generated\Models;
use Microsoft\Graph\Generated\Users\Item\MailFolders\Item\Messages\MessagesRequestBuilderGetQueryParameters;
use Microsoft\Graph\Generated\Users\Item\MailFolders\Item\Messages\MessagesRequestBuilderGetRequestConfiguration;
use Microsoft\Graph\Generated\Users\Item\SendMail\SendMailPostRequestBody;
use Microsoft\Graph\Generated\Users\Item\UserItemRequestBuilderGetQueryParameters;
use Microsoft\Graph\Generated\Users\Item\UserItemRequestBuilderGetRequestConfiguration;
use Microsoft\Graph\GraphRequestAdapter;
use Microsoft\Graph\GraphServiceClient;
use Microsoft\Kiota\Abstractions\Authentication\BaseBearerTokenAuthenticationProvider;

require_once 'DeviceCodeTokenProvider.php';

Adicione o seguinte código à classe GraphHelper.

private static string $clientId = '';
private static string $tenantId = '';
private static string $graphUserScopes = '';
private static DeviceCodeTokenProvider $tokenProvider;
private static GraphServiceClient $userClient;

public static function initializeGraphForUserAuth(): void {
    GraphHelper::$clientId = $_ENV['CLIENT_ID'];
    GraphHelper::$tenantId = $_ENV['TENANT_ID'];
    GraphHelper::$graphUserScopes = $_ENV['GRAPH_USER_SCOPES'];

    GraphHelper::$tokenProvider = new DeviceCodeTokenProvider(
        GraphHelper::$clientId,
        GraphHelper::$tenantId,
        GraphHelper::$graphUserScopes);
    $authProvider = new BaseBearerTokenAuthenticationProvider(GraphHelper::$tokenProvider);
    $adapter = new GraphRequestAdapter($authProvider);
    GraphHelper::$userClient = GraphServiceClient::createWithRequestAdapter($adapter);
}

Substitua a função empty initializeGraph no main.php pelo seguinte.

function initializeGraph(): void {
    GraphHelper::initializeGraphForUserAuth();
}

Este código carrega informações do ficheiro .env e inicializa duas propriedades, um DeviceCodeTokenProvider objeto e um GraphServiceClient objeto. O DeviceCodeTokenProvider objeto será utilizado para pedir um token de acesso e o GraphServiceClient objeto será utilizado para fazer chamadas para o Microsoft Graph.

Testar o fluxo de código do dispositivo

Em seguida, adicione código para obter um token de acesso a GraphHelperpartir do .

Adicione a função a seguir à classe GraphHelper.

public static function getUserToken(): string {
    return GraphHelper::$tokenProvider
        ->getAuthorizationTokenAsync('https://graph.microsoft.com')->wait();
}

Substitua a função empty displayAccessToken no main.php pelo seguinte.

function displayAccessToken(): void {
    try {
        $token = GraphHelper::getUserToken();
        print('User token: '.$token.PHP_EOL.PHP_EOL);
    } catch (Exception $e) {
        print('Error getting access token: '.$e->getMessage().PHP_EOL.PHP_EOL);
    }
}

Crie e execute a aplicação. Introduza 1 quando lhe for pedida uma opção. A aplicação apresenta um URL e um código de dispositivo.

$ php main.php

PHP Graph Tutorial

Please choose one of the following options:
0. Exit
1. Display access token
2. List my inbox
3. Send mail
4. 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 browser e navegue para o URL apresentado. Introduza o código fornecido e inicie sessão.

Importante

Tenha em atenção todas as contas existentes do Microsoft 365 com sessão iniciada no browser ao navegar para https://microsoft.com/devicelogino . Utilize funcionalidades do browser, como perfis, modo de convidado ou modo privado para garantir que se autentica como a conta que pretende utilizar para testes.
Depois de concluído, regresse à aplicação para ver o token de acesso.

Dica

Apenas para fins de validação e depuração, pode descodificar tokens de acesso de utilizador (apenas para contas escolares ou profissionais) com o analisador de tokens online da Microsoft em https://jwt.ms. Isto pode ser útil se encontrar erros de token ao chamar o Microsoft Graph. Por exemplo, verificar se a scp afirmação no token contém os âmbitos de permissão esperados do Microsoft Graph.

Obter usuário

15 minutos restantes

Nesta secção, irá incorporar o Microsoft Graph na aplicação. Para esta aplicação, irá utilizar o SDK do Microsoft Graph para PHP para fazer chamadas para o Microsoft Graph.

Adicione o seguinte código à classe GraphHelper.

public static function getUser(): Models\User {
    $configuration = new UserItemRequestBuilderGetRequestConfiguration();
    $configuration->queryParameters = new UserItemRequestBuilderGetQueryParameters();
    $configuration->queryParameters->select = ['displayName','mail','userPrincipalName'];
    return GraphHelper::$userClient->me()->get($configuration)->wait();
}

Substitua a função empty greetUser no main.php pelo seguinte.

function greetUser(): void {
    try {
        $user = GraphHelper::getUser();
        print('Hello, '.$user->getDisplayName().'!'.PHP_EOL);

        // For Work/school accounts, email is in Mail property
        // Personal accounts, email is in UserPrincipalName
        $email = $user->getMail();
        if (empty($email)) {
            $email = $user->getUserPrincipalName();
        }
        print('Email: '.$email.PHP_EOL.PHP_EOL);
    } catch (Exception $e) {
        print('Error getting user: '.$e->getMessage().PHP_EOL.PHP_EOL);
    }
}

Se executar a aplicação agora, depois de iniciar sessão na aplicação dá-lhe as boas-vindas pelo nome.

Hello, Megan Bowen!
Email: MeganB@contoso.com

Código explicado

Considere o código na getUser função . São apenas algumas linhas, mas há alguns detalhes importantes a notar.

Aceder a 'eu'

A função cria um pedido para a API Obter utilizador . Esta API está acessível de duas formas:

GET /me
GET /users/{user-id}

Neste caso, o código chamará o ponto final da GET /me API. Este é um método de atalho para obter o utilizador autenticado sem saber o respetivo ID de utilizador.

Observação

Uma vez que o ponto final da GET /me API obtém o utilizador autenticado, só está disponível para aplicações que utilizem a autenticação de utilizador. As aplicações de autenticação apenas de aplicações não podem aceder a este ponto final.

Pedir propriedades específicas

A função utiliza o parâmetro de consulta $select para especificar o conjunto de propriedades de que necessita.

Tipo de retorno fortemente escrito

A função devolve um User objeto serializado da resposta JSON da API. Uma vez que o código utiliza $select, apenas as propriedades pedidas terão valores no objeto devolvido User . Todas as outras propriedades terão valores predefinidos.

Listar caixa de entrada

12 minutos restantes

Nesta secção, irá adicionar a capacidade de listar mensagens na caixa de entrada do e-mail do utilizador.

Adicione o seguinte código à classe GraphHelper.

public static function getInbox(): Models\MessageCollectionResponse {
    $configuration = new MessagesRequestBuilderGetRequestConfiguration();
    $configuration->queryParameters = new MessagesRequestBuilderGetQueryParameters();
    // Only request specific properties
    $configuration->queryParameters->select = ['from','isRead','receivedDateTime','subject'];
    // Sort by received time, newest first
    $configuration->queryParameters->orderby = ['receivedDateTime DESC'];
    // Get at most 25 results
    $configuration->queryParameters->top = 25;
    return GraphHelper::$userClient->me()
        ->mailFolders()
        ->byMailFolderId('inbox')
        ->messages()
        ->get($configuration)->wait();
}

Substitua a função empty listInbox no main.php pelo seguinte.

function listInbox(): void {
    try {
        $messages = GraphHelper::getInbox();

        // Output each message's details
        foreach ($messages->getValue() as $message) {
            print('Message: '.$message->getSubject().PHP_EOL);
            print('  From: '.$message->getFrom()->getEmailAddress()->getName().PHP_EOL);
            $status = $message->getIsRead() ? "Read" : "Unread";
            print('  Status: '.$status.PHP_EOL);
            print('  Received: '.$message->getReceivedDateTime()->format(\DateTimeInterface::RFC2822).PHP_EOL);
        }

        $nextLink = $messages->getOdataNextLink();
        $moreAvailable = isset($nextLink) && $nextLink != '' ? 'True' : 'False';
        print(PHP_EOL.'More messages available? '.$moreAvailable.PHP_EOL.PHP_EOL);
    } catch (Exception $e) {
        print('Error getting user\'s inbox: '.$e->getMessage().PHP_EOL.PHP_EOL);
    }
}

Execute a aplicação, inicie sessão e selecione a opção 2 para listar a 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. Make a Graph call
2
Message: Updates from Ask HR and other communities
  From: Contoso Demo on Yammer
  Status: Read
  Received: Mon, 18 Apr 2022 14:24:16 +0000
Message: Employee Initiative Thoughts
  From: Patti Fernandez
  Status: Read
  Received: Mon, 18 Apr 2022 13:52:03 +0000
Message: Voice Mail (11 seconds)
  From: Alex Wilber
  Status: Unread
  Received: Wed, 13 Apr 2022 02:30:27 +0000
Message: Our Spring Blog Update
  From: Alex Wilber
  Status: Unread
  Received: Tue, 12 Apr 2022 16:46:01 +0000
Message: Atlanta Flight Reservation
  From: Alex Wilber
  Status: Unread
  Received: Mon, 11 Apr 2022 13:39:10 +0000
Message: Atlanta Trip Itinerary - down time
  From: Alex Wilber
  Status: Unread
  Received: Fri, 08 Apr 2022 18:36:01 +0000

...

More messages available? True

Código explicado

Considere o código na getInbox função .

Aceder a pastas de correio conhecidas

A função passa /me/mailFolders/inbox/messages para o construtor de pedidos, que cria um pedido para a API Listar mensagens . Uma vez que inclui o /mailFolders/inbox segmento, a API só irá devolver mensagens na pasta de correio pedida. Neste caso, uma vez que a caixa de entrada é uma pasta predefinida e conhecida dentro da caixa de correio de um utilizador, é acessível através do nome conhecido. As pastas não predefinidas são acedidas da mesma forma ao substituir o nome conhecido pela propriedade ID da pasta de correio. Para obter detalhes sobre os nomes de pastas conhecidos disponíveis, consulte mailFolder resource type (Tipo de recurso mailFolder).

Aceder a uma coleção

Ao contrário da getUser função da secção anterior, que devolve um único objeto, este método devolve uma coleção de mensagens. A maioria das APIs no Microsoft Graph que devolvem uma coleção não devolvem todos os resultados disponíveis numa única resposta. Em vez disso, utilizam a paginação para devolver uma parte dos resultados, ao mesmo tempo que fornecem um método para os clientes solicitarem a "página" seguinte.

Tamanhos de página predefinidos

As APIs que utilizam a paginação implementam um tamanho de página predefinido. Para mensagens, o valor predefinido é 10. Os clientes podem pedir mais (ou menos) através do parâmetro de consulta $top . No getInbox, isto é conseguido com a queryParameters->top propriedade nos parâmetros de consulta.

Observação

O valor transmitido queryParameters->top é um limite superior e não um número explícito. A API devolve um número de mensagens até ao valor especificado.

Obter páginas subsequentes

Se existirem mais resultados disponíveis no servidor, as respostas da coleção incluem uma @odata.nextLink propriedade com um URL de API para aceder à página seguinte. O SDK PHP expõe-no como o getOdataNextLink método nos objetos de pedido de coleção. Se este método devolver uma cadeia não vazia, existem mais resultados disponíveis. Para obter mais informações, consulte Page through a collection using the Microsoft Graph SDKs (Página através de uma coleção com os SDKs do Microsoft Graph).

Classificando coleções

A função utiliza o parâmetro de consulta $orderby para pedir resultados ordenados quando a mensagem é recebida (receivedDateTime propriedade). Inclui a palavra-chave para que as DESC mensagens recebidas mais recentemente sejam listadas primeiro.

Enviar email

8 minutos restantes

Nesta secção, irá adicionar a capacidade de enviar uma mensagem de e-mail como utilizador autenticado.

Adicione o seguinte código à classe GraphHelper.

public static function sendMail(string $subject, string $body, string $recipient): void {
    $message = new Models\Message();
    $message->setSubject($subject);

    $itemBody = new Models\ItemBody();
    $itemBody->setContent($body);
    $itemBody->setContentType(new Models\BodyType(Models\BodyType::TEXT));
    $message->setBody($itemBody);

    $email = new Models\EmailAddress();
    $email->setAddress($recipient);
    $to = new Models\Recipient();
    $to->setEmailAddress($email);
    $message->setToRecipients([$to]);

    $sendMailBody = new SendMailPostRequestBody();
    $sendMailBody->setMessage($message);

    GraphHelper::$userClient->me()->sendMail()->post($sendMailBody)->wait();
}

Substitua a função empty sendMail no main.php pelo seguinte.

function sendMail(): void {
    try {
        // Send mail to the signed-in user
        // Get the user for their email address
        $user = GraphHelper::getUser();

        // For Work/school accounts, email is in Mail property
        // Personal accounts, email is in UserPrincipalName
        $email = $user->getMail();
        if (empty($email)) {
            $email = $user->getUserPrincipalName();
        }

        GraphHelper::sendMail('Testing Microsoft Graph', 'Hello world!', $email);

        print(PHP_EOL.'Mail sent.'.PHP_EOL.PHP_EOL);
    } catch (Exception $e) {
        print('Error sending mail: '.$e->getMessage().PHP_EOL.PHP_EOL);
    }
}

Execute a aplicação, inicie sessão e selecione a opção 3 para enviar um e-mail para si próprio.
```
Please choose one of the following options:
0. Exit
1. Display access token
2. List my inbox
3. Send mail
4. Make a Graph call
3

Mail sent.
```
Observação

Se estiver a testar com um inquilino de programador do Programa para Programadores do Microsoft 365, o e-mail que enviar poderá não ser entregue e poderá receber um relatório de entrega sem fins lucrativos. Se isto lhe acontecer, contacte o suporte através do centro de administração do Microsoft 365.
Para verificar se a mensagem foi recebida, selecione a opção 2 para listar a sua caixa de entrada.

Código explicado

Considere o código na sendMail função .

Enviar correio

A função utiliza o $userClient->me()->sendMail() construtor de pedidos, que cria um pedido para a API enviar correio . O construtor de pedidos utiliza um corpo do pedido que contém a mensagem a enviar.

Criar objetos

Ao contrário das chamadas anteriores para o Microsoft Graph que só leem dados, esta chamada cria dados. Para tal, crie uma matriz associativa que represente os dados, defina as propriedades pretendidas e, em seguida, envie-as na chamada à API. Uma vez que a chamada está a enviar dados, o POST método é utilizado em vez de GET.

Opcional: adicionar o seu próprio código

5 minutos restantes

Nesta secção, irá adicionar as suas próprias capacidades do Microsoft Graph à aplicação. Pode ser um fragmento de código da documentação do Microsoft Graph ou do Graph Explorer ou código que criou. Esta secção é opcional.

Atualizar o aplicativo

Adicione o seguinte código à classe GraphHelper.

public static function makeGraphCall(): void {
    // INSERT YOUR CODE HERE
}

Substitua a função empty makeGraphCall no main.php pelo seguinte.

function makeGraphCall(): void {
    try {
        GraphHelper::makeGraphCall();
    } catch (Exception $e) {
        print(PHP_EOL.'Error making Graph call'.PHP_EOL.PHP_EOL);
    }
}

Escolher uma API

Localize uma API no Microsoft Graph que gostaria de experimentar. Por exemplo, a API Criar evento . Pode utilizar um dos exemplos na documentação da API ou criar o seu próprio pedido de API.

Configurar as permissões

Verifique a secção Permissões da documentação de referência da API escolhida para ver que métodos de autenticação são suportados. Algumas APIs não suportam apenas aplicações ou contas Microsoft pessoais, por exemplo.

Para chamar uma API com autenticação de utilizador (se a API suportar a autenticação de utilizador (delegado), adicione o âmbito de permissão necessário em .env.
Para chamar uma API com autenticação apenas de aplicação, veja o tutorial de autenticação apenas de aplicação .

Adicionar o código

Adicione o código à makeGraphCall função no GraphHelper.php.

Compartilhar via

Criar aplicativos PHP com o Microsoft Graph

Pré-requisitos

Registrar o aplicativo no portal

Registar aplicação para autenticação de utilizador

Criar uma aplicação de consola PHP

Instalar dependências

Carregar as definições da aplicação

Design do aplicativo

Adicionar autenticação de utilizador

Criar fornecedor de tokens de acesso

Configurar o cliente do Graph para autenticação de utilizador

Testar o fluxo de código do dispositivo

Obter usuário

Código explicado

Aceder a 'eu'

Pedir propriedades específicas

Tipo de retorno fortemente escrito

Listar caixa de entrada

Código explicado

Aceder a pastas de correio conhecidas

Aceder a uma coleção

Tamanhos de página predefinidos

Obter páginas subsequentes

Classificando coleções

Enviar email

Código explicado

Enviar correio

Criar objetos

Opcional: adicionar o seu próprio código

Atualizar o aplicativo

Escolher uma API

Configurar as permissões

Adicionar o código

Parabéns!

Exemplos de PHP