Erstellen von PHP-Apps mit Microsoft Graph

Artikel
Developer (Anfänger)
29 Minuten bis zum Abschluss

In diesem Tutorial erfahren Sie, wie Sie eine PHP-Konsolen-App erstellen, die microsoft Graph-API verwendet, um im Namen eines Benutzers auf Daten zuzugreifen.

Hinweis

Informationen zur Verwendung von Microsoft Graph für den Zugriff auf Daten mithilfe der reinen App-Authentifizierung finden Sie in diesem Tutorial zur reinen App-Authentifizierung.

In diesem Lernprogramm wird Folgendes vermittelt:

Tipp

Alternativ zu diesem Tutorial können Sie den vollständigen Code über das Schnellstarttool herunterladen, das die App-Registrierung und -Konfiguration automatisiert. Der heruntergeladene Code funktioniert ohne Änderungen.

Sie können auch das GitHub-Repository herunterladen oder klonen und die Anweisungen in der INFODATEI befolgen, um eine Anwendung zu registrieren und das Projekt zu konfigurieren.

Voraussetzungen

Bevor Sie mit diesem Tutorial beginnen, sollten PHP und Composer auf Ihrem Entwicklungscomputer installiert sein.

Sie sollten auch über ein Microsoft-Geschäfts-, Schul- oder Unikonto mit einem Exchange Online Postfach verfügen. Wenn Sie nicht über einen Microsoft 365-Mandanten verfügen, können Sie sich über das Microsoft 365-Entwicklerprogramm für einen mandantenfähigen Mandanten qualifizieren. Weitere Informationen finden Sie in den häufig gestellten Fragen. Alternativ können Sie sich für eine kostenlose 1-monatige Testversion registrieren oder einen Microsoft 365-Plan erwerben.

Hinweis

Dieses Tutorial wurde mit PHP-Version 8.1.5 und Composer-Version 2.3.5 geschrieben. Die Schritte in diesem Leitfaden funktionieren möglicherweise mit anderen Versionen, die jedoch nicht getestet wurden.

Registrieren der App im Portal

28 Minuten verbleibend

In dieser Übung registrieren Sie eine neue Anwendung in Azure Active Directory, um die Benutzerauthentifizierung zu aktivieren. Sie können eine Anwendung über das Azure Active Directory Admin Center oder mithilfe des Microsoft Graph PowerShell SDK registrieren.

Registrieren der Anwendung für die Benutzerauthentifizierung

In diesem Abschnitt registrieren Sie eine Anwendung, die die Benutzerauthentifizierung mithilfe des Gerätecodeflows unterstützt.

Azure AD Admin Center
PowerShell

Öffnen Sie einen Browser, navigieren Sie zum Azure Active Directory Admin Center , und melden Sie sich mit einem Geschäfts-, Schul- oder Unikonto an.
Wählen Sie in der linken Navigationsleiste Azure Active Directory aus, und wählen Sie dann App-Registrierungen unter Verwalten aus.
Wählen Sie Neue Registrierung aus. Geben Sie einen Namen für Ihre Anwendung ein, Graph User Auth Tutorialz. B. .

Legen Sie unterstützte Kontotypen wie gewünscht fest. Mögliche Optionen:

Option	Wer kann sich anmelden?
Nur Konten in diesem Organisationsverzeichnis	Nur Benutzer in Ihrem Microsoft 365-organization
Konten in einem beliebigen Organisationsverzeichnis	Benutzer in allen Microsoft 365-organization (Geschäfts-, Schul- oder Unikonten)
Konten in einem beliebigen Organisationsverzeichnis ... und persönliche Microsoft-Konten	Benutzer in allen Microsoft 365 organization (Geschäfts-, Schul- oder Unikonten) und persönlichen Microsoft-Konten

Lassen Sie URI umleiten leer.
Wählen Sie Registrieren aus. Kopieren Sie auf der Seite Übersicht der Anwendung den Wert der Anwendungs-ID (Client-ID), und speichern Sie ihn. Sie benötigen ihn im nächsten Schritt. Wenn Sie nur Konten in diesem Organisationsverzeichnis für Unterstützte Kontotypen ausgewählt haben, kopieren Sie auch die Verzeichnis-ID (Mandant), und speichern Sie sie.
Wählen Sie unter Verwalten die Option Authentifizierung aus. Suchen Sie den Abschnitt Erweiterte Einstellungen , und ändern Sie die Umschaltfläche Öffentliche Clientflows zulassen auf Ja, und wählen Sie dann Speichern aus.

Um PowerShell verwenden zu können, benötigen Sie das Microsoft Graph PowerShell SDK. Falls sie nicht vorhanden ist, finden Sie unter Installieren des Microsoft Graph PowerShell SDK Anweisungen zur Installation.

Wichtig

Das PowerShell-Skript erfordert ein Geschäfts-, Schul- oder Unikonto mit der Rolle Anwendungsadministrator, Cloudanwendungsadministrator oder globaler Administrator. Wenn Ihr Konto über die Rolle Anwendungsentwickler verfügt, können Sie sich im Azure AD Admin Center registrieren.

Erstellen Sie eine neue Datei mit dem NamenRegisterAppForUserAuth.ps1 , und fügen Sie den folgenden Code hinzu.

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"
}

Speichern Sie die Datei.
Öffnen Sie PowerShell, und ändern Sie das aktuelle Verzeichnis in den Speicherort von RegisterAppForUserAuth.ps1.

Führen Sie den folgenden Befehl aus, und <ersetzen Sie audience-value> durch den gewünschten Wert (siehe Tabelle unten).

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

SignInAudience-Wert	Wer kann sich anmelden?
`AzureADMyOrg`	Nur Benutzer in Ihrem Microsoft 365-organization
`AzureADMultipleOrgs`	Benutzer in allen Microsoft 365-organization (Geschäfts-, Schul- oder Unikonten)
`AzureADandPersonalMicrosoftAccount`	Benutzer in allen Microsoft 365 organization (Geschäfts-, Schul- oder Unikonten) und persönlichen Microsoft-Konten
`PersonalMicrosoftAccount`	Nur persönliche Microsoft-Konten

Folgen Sie der Aufforderung, um in einem Browser zu öffnen https://microsoft.com/devicelogin , geben Sie den bereitgestellten Code ein, und schließen Sie den Authentifizierungsprozess ab.
Kopieren Sie die Werte für Client-ID und Authentifizierungsmandanten aus der Skriptausgabe. Sie benötigen diese Werte im nächsten Schritt.
```
SUCCESS
Client ID: 2fb1652f-a9a0-4db9-b220-b224b8d9d38b
Auth tenant: common
```

Hinweis

Beachten Sie, dass Sie keine Microsoft Graph-Berechtigungen für die App-Registrierung konfiguriert haben. Dies liegt daran, dass im Beispiel die dynamische Zustimmung verwendet wird, um bestimmte Berechtigungen für die Benutzerauthentifizierung anzufordern.

Erstellen einer PHP-Konsolen-App

25 Minuten verbleibend

Initialisieren Sie zunächst ein neues Composer-Projekt. Öffnen Sie Ihre Befehlszeilenschnittstelle (CLI) in einem Verzeichnis, in dem Sie das Projekt erstellen möchten. Führen Sie den folgenden Befehl aus.

composer init

Beantworten Sie die Eingabeaufforderungen. Sie können die Standardwerte für die meisten Fragen übernehmen, aber auf Folgendes antworten n :

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

Installieren von Abhängigkeiten

Bevor Sie mit dem Vorgang fortfahren, fügen Sie einige zusätzliche Abhängigkeiten hinzu, die Sie später verwenden werden.

Microsoft Graph SDK für PHP , um Aufrufe an Microsoft Graph zu senden.
vlucas/phpdotenv zum Lesen von Umgebungsvariablen aus ENV-Dateien.

Führen Sie den folgenden Befehl in Ihrer CLI aus, um die Abhängigkeiten zu installieren.

composer require microsoft/microsoft-graph vlucas/phpdotenv

Laden von Anwendungseinstellungen

In diesem Abschnitt fügen Sie dem Projekt die Details Ihrer App-Registrierung hinzu.

Erstellen Sie eine Datei im Stammverzeichnis Ihres Projekts mit dem Namen .env , und fügen Sie den folgenden Code hinzu.
```
CLIENT_ID=YOUR_CLIENT_ID_HERE
TENANT_ID=common
GRAPH_USER_SCOPES='user.read mail.read mail.send'
```

Aktualisieren Sie die Werte gemäß der folgenden Tabelle.

Einstellung	Wert
`CLIENT_ID`	Die Client-ID Ihrer App-Registrierung
`TENANT_ID`	Wenn Sie die Option ausgewählt haben, nur Benutzern in Ihrem organization die Anmeldung zu erlauben, ändern Sie diesen Wert in Ihre Mandanten-ID. Übernehmen Sie andernfalls den Wert `common`.

Wichtig

Wenn Sie quellcodeverwaltung wie Git verwenden, ist jetzt ein guter Zeitpunkt, um die ENV-Datei aus der Quellcodeverwaltung auszuschließen, um zu vermeiden, dass Versehentlich Ihre App-ID verloren geht.

Entwerfen der App

In diesem Abschnitt erstellen Sie ein einfaches konsolenbasiertes Menü.

Erstellen Sie eine Datei im Stammverzeichnis Ihres Projekts mit dem Namen Standard.php. Fügen Sie die öffnenden und schließenden PHP-Tags hinzu.
```
<?php
?>
```

Fügen Sie den folgenden Code zwischen den PHP-Tags hinzu.

// 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);
    }
}

Fügen Sie die folgenden Platzhaltermethoden am Ende der Datei vor dem schließenden PHP-Tag hinzu. Sie implementieren sie in späteren Schritten.

function initializeGraph(): void {
    // TODO
}

function greetUser(): void {
    // TODO
}

function displayAccessToken(): void {
    // TODO
}

function listInbox(): void {
    // TODO
}

function sendMail(): void {
    // TODO
}

function makeGraphCall(): void {
    // TODO
}

Dadurch wird ein einfaches Menü implementiert und die Auswahl des Benutzers aus der Befehlszeile gelesen.

Hinzufügen der Benutzerauthentifizierung

20 Minuten verbleibend

In diesem Abschnitt erweitern Sie die Anwendung aus der vorherigen Übung, um die Authentifizierung mit Azure AD zu unterstützen. Dies ist erforderlich, um das erforderliche OAuth-Zugriffstoken zum Aufrufen von Microsoft Graph abzurufen.

Erstellen eines Zugriffstokenanbieters

Das Microsoft Graph SDK enthält Authentifizierungsanbieter, die auf dem PHP League OAuth2-Client basieren. In diesem Tutorial verwenden Sie jedoch den Gerätecodeflow , um Zugriffstoken abzurufen. Die enthaltenen Authentifizierungsanbieter implementieren diesen Flow nicht, sodass Sie einen benutzerdefinierten Zugriffstokenanbieter implementieren.

Erstellen Sie eine neue Datei im Stammverzeichnis Ihres Projekts mit dem Namen DeviceCodeTokenProvider.php. Fügen Sie den folgenden Code hinzu.

<?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;
    }
}
?>

Konfigurieren des Graph-Clients für die Benutzerauthentifizierung

In diesem Abschnitt verwenden Sie die DeviceCodeTokenProvider -Klasse, um mithilfe des Gerätecodeflows ein Zugriffstoken anzufordern.

Erstellen Sie im Stammverzeichnis Ihres Projekts eine neue Datei mit dem Namen GraphHelper.php. Fügen Sie den folgenden Code hinzu.
```
<?php
class GraphHelper {
}
?>
```

Fügen Sie die folgenden using Anweisungen innerhalb der PHP-Tags hinzu.

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';

Fügen Sie der GraphHelper-Klasse den folgenden Code hinzu.

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);
}

Ersetzen Sie die leere initializeGraph Funktion in Standard.php durch Folgendes.

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

Dieser Code lädt Informationen aus der ENV-Datei und initialisiert zwei Eigenschaften, ein DeviceCodeTokenProvider -Objekt und ein GraphServiceClient -Objekt. Das DeviceCodeTokenProvider -Objekt wird verwendet, um ein Zugriffstoken anzufordern, und das GraphServiceClient -Objekt wird für Aufrufe an Microsoft Graph verwendet.

Testen des Gerätecodeflows

Fügen Sie als Nächstes Code hinzu, um ein Zugriffstoken GraphHelpervon abzurufen.

Fügen Sie die folgende Funktion zur GraphHelper-Klasse hinzu:

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

Ersetzen Sie die leere displayAccessToken Funktion in Standard.php durch Folgendes.

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);
    }
}

Erstellen Sie die App, und führen Sie sie aus. Geben Sie ein 1 , wenn Sie zur Eingabe einer Option aufgefordert werden. Die Anwendung zeigt eine URL und den Gerätecode an.

$ 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.

Öffnen Sie einen Browser, und navigieren Sie zu der angezeigten URL. Geben Sie den angegebenen Code ein, und melden Sie sich an.

Wichtig

Achten Sie auf vorhandene Microsoft 365-Konten, die bei Ihrem Browser angemeldet sind, wenn Sie zu https://microsoft.com/deviceloginnavigieren. Verwenden Sie Browserfeatures wie Profile, Gastmodus oder privaten Modus, um sicherzustellen, dass Sie sich als das Konto authentifizieren, das Sie zu Testzwecken verwenden möchten.
Kehren Sie nach Abschluss des Vorgangs zur Anwendung zurück, um das Zugriffstoken anzuzeigen.

Tipp

Nur zu Validierungs- und Debugzwecken können Sie Benutzerzugriffstoken (nur für Geschäfts-, Schul- oder Unikonten) decodieren, indem Sie den Onlinetokenparser von Microsoft unter verwendenhttps://jwt.ms. Dies kann nützlich sein, wenn beim Aufrufen von Microsoft Graph Tokenfehler auftreten. Beispielsweise wird überprüft, ob der scp Anspruch im Token die erwarteten Microsoft Graph-Berechtigungsbereiche enthält.

Benutzer abrufen

15 Minuten verbleibend

In diesem Abschnitt integrieren Sie Microsoft Graph in die Anwendung. Für diese Anwendung verwenden Sie das Microsoft Graph SDK für PHP , um Aufrufe an Microsoft Graph zu senden.

Fügen Sie der GraphHelper-Klasse den folgenden Code hinzu.

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();
}

Ersetzen Sie die leere greetUser Funktion in Standard.php durch Folgendes.

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);
    }
}

Wenn Sie die App jetzt ausführen, werden Sie nach der Anmeldung in der App mit dem Namen begrüßt.

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

Code erläutert

Betrachten Sie den Code in der getUser Funktion. Es sind nur wenige Zeilen, aber es sind einige wichtige Details zu beachten.

Zugreifen auf "me"

Die Funktion erstellt eine Anforderung an die Api zum Abrufen von Benutzern . Auf diese API kann auf zwei Arten zugegriffen werden:

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

In diesem Fall ruft der Code den GET /me API-Endpunkt auf. Dies ist eine Verknüpfungsmethode, um den authentifizierten Benutzer abzurufen, ohne seine Benutzer-ID zu kennen.

Hinweis

Da der GET /me API-Endpunkt den authentifizierten Benutzer abruft, ist er nur für Apps verfügbar, die die Benutzerauthentifizierung verwenden. Reine App-Authentifizierungs-Apps können nicht auf diesen Endpunkt zugreifen.

Anfordern bestimmter Eigenschaften

Die Funktion verwendet den Abfrageparameter $select , um die benötigten Eigenschaften anzugeben.

Stark typisierter Rückgabetyp

Die Funktion gibt ein User Objekt zurück, das aus der JSON-Antwort der API deserialisiert wurde. Da der Code verwendet $select, verfügen nur die angeforderten Eigenschaften über Werte im zurückgegebenen User Objekt. Alle anderen Eigenschaften verfügen über Standardwerte.

Posteingang auflisten

12 Minuten verbleibend

In diesem Abschnitt fügen Sie die Möglichkeit hinzu, Nachrichten im E-Mail-Posteingang des Benutzers aufzulisten.

Fügen Sie der GraphHelper-Klasse den folgenden Code hinzu.

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();
}

Ersetzen Sie die leere listInbox Funktion in Standard.php durch Folgendes.

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);
    }
}

Führen Sie die App aus, melden Sie sich an, und wählen Sie Option 2 aus, um Ihren Posteingang aufzulisten.

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

Code erläutert

Betrachten Sie den Code in der getInbox Funktion.

Zugreifen auf bekannte E-Mail-Ordner

Die -Funktion wird an den Anforderungs-Generator übergeben /me/mailFolders/inbox/messages , der eine Anforderung an die API zum Auflisten von Nachrichten erstellt. Da sie das /mailFolders/inbox Segment enthält, gibt die API nur Nachrichten im angeforderten E-Mail-Ordner zurück. Da der Posteingang in diesem Fall ein bekannter Standardordner innerhalb des Postfachs eines Benutzers ist, ist er über seinen bekannten Namen zugänglich. Auf nicht standardmäßige Ordner wird auf die gleiche Weise zugegriffen, indem der bekannte Name durch die ID-Eigenschaft des E-Mail-Ordners ersetzt wird. Ausführliche Informationen zu den verfügbaren bekannten Ordnernamen finden Sie unter mailFolder-Ressourcentyp.

Zugreifen auf eine Sammlung

Im Gegensatz zur getUser Funktion aus dem vorherigen Abschnitt, die ein einzelnes Objekt zurückgibt, gibt diese Methode eine Auflistung von Nachrichten zurück. Die meisten APIs in Microsoft Graph, die eine Sammlung zurückgeben, geben nicht alle verfügbaren Ergebnisse in einer einzigen Antwort zurück. Stattdessen wird paging verwendet, um einen Teil der Ergebnisse zurückzugeben, während clients eine Methode zum Anfordern der nächsten "Seite" bereitstellen.

Standardseitengrößen

APIs, die Paging verwenden, implementieren eine Standardseitengröße. Für Nachrichten ist der Standardwert 10. Clients können mithilfe des abfrageparameters $top mehr (oder weniger) anfordern. In getInboxwird dies mit der queryParameters->top -Eigenschaft in den Abfrageparametern erreicht.

Hinweis

Der übergebene queryParameters->top Wert ist eine obere Grenze, keine explizite Zahl. Die API gibt eine Anzahl von Nachrichten bis zum angegebenen Wert zurück.

Abrufen nachfolgender Seiten

Wenn auf dem Server weitere Ergebnisse verfügbar sind, enthalten Sammlungsantworten eine @odata.nextLink Eigenschaft mit einer API-URL für den Zugriff auf die nächste Seite. Das PHP SDK macht dies als Methode getOdataNextLink für Sammlungsanforderungsobjekte verfügbar. Wenn diese Methode eine nicht leere Zeichenfolge zurückgibt, stehen weitere Ergebnisse zur Verfügung. Weitere Informationen finden Sie unter Seite durch eine Sammlung mit den Microsoft Graph SDKs.

Sortieren von Sammlungen

Die Funktion verwendet den Abfrageparameter $orderby , um Ergebnisse anzufordern, die nach dem Zeitpunkt sortiert sind, zu dem die Nachricht empfangen wird (receivedDateTime -Eigenschaft). Sie enthält die DESC Schlüsselwort (keyword), sodass kürzlich empfangene Nachrichten zuerst aufgeführt werden.

Nachrichten senden

8 Minuten verbleibend

In diesem Abschnitt fügen Sie die Möglichkeit hinzu, eine E-Mail-Nachricht als authentifizierten Benutzer zu senden.

Fügen Sie der GraphHelper-Klasse den folgenden Code hinzu.

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();
}

Ersetzen Sie die leere sendMail Funktion in Standard.php durch Folgendes.

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);
    }
}

Führen Sie die App aus, melden Sie sich an, und wählen Sie Option 3 aus, um eine E-Mail an sich selbst zu senden.
```
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.
```
Hinweis

Wenn Sie mit einem Entwicklermandanten aus dem Microsoft 365-Entwicklerprogramm testen, wird die von Ihnen gesendete E-Mail möglicherweise nicht zugestellt, und Sie erhalten möglicherweise einen Nichtzustellbarkeitsbericht. Wenn Ihnen dies passiert, wenden Sie sich bitte über den Microsoft 365 Admin Center an den Support.
Um zu überprüfen, ob die Nachricht empfangen wurde, wählen Sie Option 2 aus, um Ihren Posteingang aufzulisten.

Code erläutert

Betrachten Sie den Code in der sendMail Funktion.

Senden von E-Mails

Die Funktion verwendet den Anforderungs-Generator $userClient->me()->sendMail() , der eine Anforderung an die API zum Senden von E-Mails erstellt. Der Anforderungs-Generator verwendet einen Anforderungstext, der die zu sendende Nachricht enthält.

Erstellen von Objekten

Im Gegensatz zu den vorherigen Aufrufen von Microsoft Graph, die nur Daten lesen, werden mit diesem Aufruf Daten erstellt. Um dies mit der Clientbibliothek zu tun, erstellen Sie ein assoziatives Array, das die Daten darstellt, legen die gewünschten Eigenschaften fest und senden sie dann im API-Aufruf. Da der Aufruf Daten sendet, wird die POST -Methode anstelle von GETverwendet.

Optional: Fügen Sie Ihren eigenen Code hinzu.

5 Minuten verbleibend

In diesem Abschnitt fügen Sie der Anwendung Ihre eigenen Microsoft Graph-Funktionen hinzu. Dies kann ein Codeausschnitt aus der Microsoft Graph-Dokumentation oder graph Explorer oder Code sein, den Sie erstellt haben. Dieser Abschnitt ist optional.

Aktualisieren der App

Fügen Sie der GraphHelper-Klasse den folgenden Code hinzu.

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

Ersetzen Sie die leere makeGraphCall Funktion in Standard.php durch Folgendes.

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

Auswählen einer API

Suchen Sie eine API in Microsoft Graph, die Sie ausprobieren möchten. Beispiel: Die Api zum Erstellen eines Ereignisses . Sie können eines der Beispiele in der API-Dokumentation verwenden oder Eine eigene API-Anforderung erstellen.

Konfigurieren von Berechtigungen

Überprüfen Sie den Abschnitt Berechtigungen der Referenzdokumentation für Die ausgewählte API, um zu sehen, welche Authentifizierungsmethoden unterstützt werden. Einige APIs unterstützen z. B. keine reinen Apps oder persönlichen Microsoft-Konten.

Um eine API mit Benutzerauthentifizierung aufzurufen (wenn die API die (delegierte) Benutzerauthentifizierung unterstützt), fügen Sie den erforderlichen Berechtigungsbereich in .env hinzu.
Informationen zum Aufrufen einer API mit nur app-Authentifizierung finden Sie im Tutorial zur reinen App-Authentifizierung .

Fügen Sie Ihren Code hinzu

Fügen Sie Ihren Code der makeGraphCall Funktion in GraphHelper.php hinzu.

Erstellen von PHP-Apps mit Microsoft Graph

Voraussetzungen

Registrieren der App im Portal

Registrieren der Anwendung für die Benutzerauthentifizierung

Erstellen einer PHP-Konsolen-App

Installieren von Abhängigkeiten

Laden von Anwendungseinstellungen

Entwerfen der App

Hinzufügen der Benutzerauthentifizierung

Erstellen eines Zugriffstokenanbieters

Konfigurieren des Graph-Clients für die Benutzerauthentifizierung

Testen des Gerätecodeflows

Benutzer abrufen

Code erläutert

Zugreifen auf "me"

Anfordern bestimmter Eigenschaften

Stark typisierter Rückgabetyp

Posteingang auflisten

Code erläutert

Zugreifen auf bekannte E-Mail-Ordner

Zugreifen auf eine Sammlung

Standardseitengrößen

Abrufen nachfolgender Seiten

Sortieren von Sammlungen

Nachrichten senden

Code erläutert

Senden von E-Mails

Erstellen von Objekten

Optional: Fügen Sie Ihren eigenen Code hinzu.

Aktualisieren der App

Auswählen einer API

Konfigurieren von Berechtigungen

Fügen Sie Ihren Code hinzu

Herzlichen Glückwunsch!

PHP-Beispiele