Microsoft Graph Developer Referenz Microsoft Graph Developer Reference

# Pakete installieren (.NET CLI)
dotnet add package Microsoft.Graph
dotnet add package Azure.Identity

using Azure.Identity;
using Microsoft.Graph;
using Microsoft.Graph.Models;

// App-only Authentication (Service Principal / Client Credentials)
var credential = new ClientSecretCredential(
    tenantId:     Environment.GetEnvironmentVariable("AZURE_TENANT_ID"),
    clientId:     Environment.GetEnvironmentVariable("AZURE_CLIENT_ID"),
    clientSecret: Environment.GetEnvironmentVariable("AZURE_CLIENT_SECRET")
);

// GraphServiceClient mit Default-Scopes
var graphClient = new GraphServiceClient(credential,
    new[] { "https://graph.microsoft.com/.default" });

// Benutzer abrufen mit $select, $filter, $top
var users = await graphClient.Users.GetAsync(req =>
{
    req.QueryParameters.Select  = new[] { "id", "displayName", "userPrincipalName", "department" };
    req.QueryParameters.Filter  = "department eq 'Engineering'";
    req.QueryParameters.Top     = 20;
    req.QueryParameters.Orderby = new[] { "displayName asc" };
});

foreach (var user in users?.Value ?? new List<User>())
{
    Console.WriteLine($"{user.DisplayName,-40} {user.UserPrincipalName}");
}

// Managed Identity (Azure Functions, App Service, VM)
var managedCred = new ManagedIdentityCredential();
var mgClient    = new GraphServiceClient(managedCred,
    new[] { "https://graph.microsoft.com/.default" });

// Einzelnen Benutzer per Id abrufen
var singleUser = await mgClient.Users["alice@contoso.com"].GetAsync();
Console.WriteLine($"UPN: {singleUser?.UserPrincipalName}");

// Benutzer erstellen
var newUser = new User
{
    DisplayName       = "Bob Müller",
    UserPrincipalName = "bob@contoso.com",
    MailNickname      = "bob",
    AccountEnabled    = true,
    PasswordProfile   = new PasswordProfile
    {
        Password                      = "TempP@ssw0rd!",
        ForceChangePasswordNextSignIn = true
    }
};
var createdUser = await graphClient.Users.PostAsync(newUser);

# Node.js (npm)
npm install @microsoft/microsoft-graph-client @azure/identity isomorphic-fetch

# Browser (npm + bundler)
npm install @microsoft/microsoft-graph-client @azure/msal-browser

import "isomorphic-fetch";
import { Client }                from "@microsoft/microsoft-graph-client";
import { TokenCredentialAuthenticationProvider } from
    "@microsoft/microsoft-graph-client/authProviders/azureTokenCredentials";
import { ClientSecretCredential } from "@azure/identity";

// App-only auth für Node.js
const credential = new ClientSecretCredential(
    process.env.AZURE_TENANT_ID,
    process.env.AZURE_CLIENT_ID,
    process.env.AZURE_CLIENT_SECRET
);

const authProvider = new TokenCredentialAuthenticationProvider(credential, {
    scopes: ["https://graph.microsoft.com/.default"]
});

const client = Client.initWithMiddleware({ authProvider });

// Benutzer mit Pagination abrufen
async function getAllUsers() {
    const allUsers = [];
    let response = await client.api("/users")
        .select("id,displayName,userPrincipalName,department")
        .filter("accountEnabled eq true")
        .top(100)
        .get();

    allUsers.push(...response.value);

    // Automatische Pagination
    while (response["@odata.nextLink"]) {
        response = await client.api(response["@odata.nextLink"]).get();
        allUsers.push(...response.value);
    }
    return allUsers;
}

// Teams-Kanal-Nachricht senden
async function sendTeamsMessage(teamId, channelId, message) {
    await client.api(`/teams/${teamId}/channels/${channelId}/messages`).post({
        body: { content: message, contentType: "html" }
    });
}

// Benutzerfotos als Blob herunterladen
async function getUserPhoto(userId) {
    const photo = await client.api(`/users/${userId}/photo/$value`)
        .responseType("blob")
        .get();
    return URL.createObjectURL(photo);
}

const users = await getAllUsers();
console.log(`Total users: ${users.length}`);

pip install msgraph-sdk azure-identity

import asyncio
from azure.identity.aio import ClientSecretCredential
from msgraph             import GraphServiceClient
from msgraph.generated.users.users_request_builder import UsersRequestBuilder
from kiota_abstractions.base_request_configuration import RequestConfiguration

async def main():
    credential = ClientSecretCredential(
        tenant_id     = "YOUR_TENANT_ID",
        client_id     = "YOUR_CLIENT_ID",
        client_secret = "YOUR_CLIENT_SECRET"
    )
    scopes = ["https://graph.microsoft.com/.default"]
    client = GraphServiceClient(credentials=credential, scopes=scopes)

    # Benutzer mit $select und $filter abfragen
    query_params = UsersRequestBuilder.UsersRequestBuilderGetQueryParameters(
        select  = ["id", "displayName", "userPrincipalName", "department"],
        filter  = "department eq 'Engineering'",
        top     = 50,
        orderby = ["displayName asc"]
    )
    config = RequestConfiguration(query_parameters=query_params)
    users  = await client.users.get(request_configuration=config)

    for user in users.value:
        print(f"{user.display_name:<40} {user.user_principal_name}")

    # Gruppen eines Benutzers abrufen
    groups = await client.users.by_user_id("alice@contoso.com").member_of.get()
    group_names = [g.display_name for g in groups.value if hasattr(g, "display_name")]
    print(f"Gruppen: {', '.join(group_names)}")

    # Benutzer aktualisieren
    from msgraph.generated.models.user import User
    patch = User(department="IT Security")
    await client.users.by_user_id("alice@contoso.com").patch(patch)

    await credential.close()

asyncio.run(main())

using Azure.Identity;
using Microsoft.Graph;

// System-Assigned Managed Identity
var miCredential = new ManagedIdentityCredential();
var miClient = new GraphServiceClient(miCredential,
    new[] { "https://graph.microsoft.com/.default" });

// User-Assigned Managed Identity
var uamiCredential = new ManagedIdentityCredential(
    clientId: "00000000-0000-0000-0000-000000000001");
var uamiClient = new GraphServiceClient(uamiCredential,
    new[] { "https://graph.microsoft.com/.default" });

// Workload Identity Federation (GitHub Actions, AKS)
// AZURE_CLIENT_ID, AZURE_TENANT_ID, AZURE_FEDERATED_TOKEN_FILE automatisch von OIDC gesetzt
var wifCredential  = new WorkloadIdentityCredential();
var wifClient      = new GraphServiceClient(wifCredential,
    new[] { "https://graph.microsoft.com/.default" });

// Certificate-basierte App-Authentifizierung (empfohlen statt Client Secret)
var certCredential = new ClientCertificateCredential(
    tenantId:    Environment.GetEnvironmentVariable("AZURE_TENANT_ID"),
    clientId:    Environment.GetEnvironmentVariable("AZURE_CLIENT_ID"),
    certificate: System.Security.Cryptography.X509Certificates.X509Certificate2
        .CreateFromPemFile("certificate.pem", "private-key.pem")
);
var certClient = new GraphServiceClient(certCredential,
    new[] { "https://graph.microsoft.com/.default" });

using Microsoft.Graph;
using Microsoft.Graph.Models;
using Microsoft.Kiota.Abstractions;

// Erweiterte Abfrage: endsWith benötigt ConsistencyLevel: eventual
var users = await graphClient.Users.GetAsync(config =>
{
    config.QueryParameters.Filter  = "endsWith(userPrincipalName, '@contoso.com')";
    config.QueryParameters.Count   = true;
    config.QueryParameters.Select  = new[] { "id", "displayName", "userPrincipalName" };
    config.QueryParameters.Top     = 100;
    config.QueryParameters.Orderby = new[] { "displayName asc" };
    config.Headers.Add("ConsistencyLevel", "eventual");
});

Console.WriteLine($"Treffer: {users?.OdataCount}");

// $search auf Benutzer (ConsistencyLevel: eventual erforderlich)
var searched = await graphClient.Users.GetAsync(config =>
{
    config.QueryParameters.Search = "\"displayName:Alice\"";
    config.QueryParameters.Select = new[] { "id", "displayName", "userPrincipalName" };
    config.Headers.Add("ConsistencyLevel", "eventual");
});

// $expand: Gruppen-Mitglieder einbetten
var group = await graphClient.Groups["GROUP_ID"].GetAsync(config =>
{
    config.QueryParameters.Select = new[] { "id", "displayName" };
    config.QueryParameters.Expand = new[] { "members($select=id,displayName,userPrincipalName)" };
});

foreach (var member in group?.Members ?? new List<DirectoryObject>())
{
    if (member is User u) Console.WriteLine($"  Member: {u.DisplayName}");
}

// $filter mit logischen Operatoren
var guestEngineers = await graphClient.Users.GetAsync(config =>
{
    config.QueryParameters.Filter =
        "userType eq 'Guest' and department eq 'Engineering'";
    config.QueryParameters.Select = new[] { "id", "displayName", "userPrincipalName" };
});

using Microsoft.Graph;
using Microsoft.Graph.Batch;

// Batch-Anfrage mit mehreren unabhängigen Anfragen
var batchRequestContent = new BatchRequestContentCollection(graphClient);

// Anfrage 1: Benutzerinformationen
var userReq = await batchRequestContent.AddBatchRequestStepAsync(
    graphClient.Users["alice@contoso.com"].ToGetRequestInformation());

// Anfrage 2: Gruppen des Benutzers
var groupsReq = await batchRequestContent.AddBatchRequestStepAsync(
    graphClient.Users["alice@contoso.com"].MemberOf.ToGetRequestInformation());

// Anfrage 3: Alle globalen Admins
var adminsReq = await batchRequestContent.AddBatchRequestStepAsync(
    graphClient.DirectoryRoles.ToGetRequestInformation());

// Batch ausführen
var batchResponse = await graphClient.Batch.PostAsync(batchRequestContent);

// Ergebnisse extrahieren
var user   = await batchResponse.GetResponseByIdAsync<User>(userReq);
var groups = await batchResponse.GetResponseByIdAsync<DirectoryObjectCollectionResponse>(groupsReq);

Console.WriteLine($"User: {user?.DisplayName}");
Console.WriteLine($"Groups: {groups?.Value?.Count}");

// JSON-Batch direkt (für HTTP-Prototypen)
/*
POST https://graph.microsoft.com/v1.0/$batch
Content-Type: application/json

{
  "requests": [
    { "id": "1", "method": "GET", "url": "/users/alice@contoso.com" },
    { "id": "2", "method": "GET", "url": "/users/alice@contoso.com/memberOf",
      "dependsOn": ["1"] },
    { "id": "3", "method": "PATCH", "url": "/users/bob@contoso.com",
      "body": { "department": "Finance" },
      "headers": { "Content-Type": "application/json" } }
  ]
}
*/

import asyncio, json
from pathlib import Path
from azure.identity.aio import ClientSecretCredential
from msgraph             import GraphServiceClient
from msgraph.generated.users.delta.delta_request_builder import DeltaRequestBuilder
from kiota_abstractions.base_request_configuration       import RequestConfiguration

DELTA_TOKEN_FILE = "delta_token.json"

async def sync_users(client: GraphServiceClient):
    """Inkrementelle Benutzersynchronisation mit Delta-Token."""
    # Delta-Token laden oder erstmaligen Sync starten
    delta_token = None
    if Path(DELTA_TOKEN_FILE).exists():
        with open(DELTA_TOKEN_FILE) as f:
            delta_token = json.load(f).get("token")

    all_changes = []

    if delta_token:
        # Inkrementeller Abruf: nur Änderungen seit letztem Sync
        url = f"https://graph.microsoft.com/v1.0/users/delta?$deltaToken={delta_token}"
        response = await client.users.delta.with_url(url).get()
    else:
        # Erster Sync: alle Benutzer + initialen Delta-Token erhalten
        query_params = DeltaRequestBuilder.DeltaRequestBuilderGetQueryParameters(
            select=["id", "displayName", "userPrincipalName", "department", "accountEnabled"]
        )
        config   = RequestConfiguration(query_parameters=query_params)
        response = await client.users.delta.get(request_configuration=config)

    # Seiten durchlaufen
    while response:
        for user in response.value:
            if hasattr(user, "additional_data") and "@removed" in user.additional_data:
                print(f"GELÖSCHT: {user.id}")
            else:
                print(f"GEÄNDERT/NEU: {user.display_name} ({user.user_principal_name})")
            all_changes.append(user)

        if response.odata_next_link:
            response = await client.users.delta.with_url(response.odata_next_link).get()
        elif response.odata_delta_link:
            # Delta-Token für nächsten Sync speichern
            token = response.odata_delta_link.split("$deltaToken=")[-1]
            with open(DELTA_TOKEN_FILE, "w") as f:
                json.dump({"token": token}, f)
            break
        else:
            break

    return all_changes

async def main():
    cred   = ClientSecretCredential("TENANT_ID", "CLIENT_ID", "CLIENT_SECRET")
    client = GraphServiceClient(credentials=cred,
                                scopes=["https://graph.microsoft.com/.default"])
    changes = await sync_users(client)
    print(f"Änderungen verarbeitet: {len(changes)}")
    await cred.close()

asyncio.run(main())

using Microsoft.Graph.Models;

// Subscription für Benutzeränderungen erstellen
var subscription = new Subscription
{
    ChangeType         = "created,updated,deleted",
    NotificationUrl    = "https://webhook.contoso.com/api/graph/notify",
    Resource           = "/users",
    ExpirationDateTime = DateTimeOffset.UtcNow.AddMinutes(4230),
    ClientState        = "SecretClientState-" + Guid.NewGuid(),
    // Rich Notifications (Ressourcendaten in Payload einbetten)
    IncludeResourceData          = true,
    EncryptionCertificate        = Convert.ToBase64String(
        certBytes),  // Öffentliches Zertifikat
    EncryptionCertificateId      = "MyCertId"
};

var createdSub = await graphClient.Subscriptions.PostAsync(subscription);
Console.WriteLine($"Subscription Id: {createdSub?.Id}, läuft ab: {createdSub?.ExpirationDateTime}");

// Subscription erneuern (vor Ablauf aufrufen)
var renewal = new Subscription
{
    ExpirationDateTime = DateTimeOffset.UtcNow.AddMinutes(4230)
};
await graphClient.Subscriptions[createdSub!.Id].PatchAsync(renewal);

// Subscription löschen
await graphClient.Subscriptions[createdSub.Id].DeleteAsync();

// Webhook-Empfänger (Azure Function / ASP.NET Controller) – Validierung
/*
[HttpPost("notify")]
public async Task<IActionResult> Notify()
{
    // Validierungsanfrage bei Subscription-Erstellung
    if (Request.Query.ContainsKey("validationToken"))
        return Content(Request.Query["validationToken"], "text/plain");

    var body = await new StreamReader(Request.Body).ReadToEndAsync();
    var notifications = JsonSerializer.Deserialize<ChangeNotificationCollection>(body);
    foreach (var notification in notifications!.Value!)
    {
        // clientState prüfen!
        if (notification.ClientState != expectedClientState) return Unauthorized();
        // Ressourcendaten verarbeiten
        _queue.Enqueue(notification.ResourceData?.Id ?? notification.Resource);
    }
    return Accepted();
}
*/

/**
 * Ruft alle Seiten einer Graph-Antwort ab.
 * Verarbeitet automatisch @odata.nextLink-Pagination und 429 Throttling.
 */
async function getAllPages(client, initialRequest) {
    const allItems = [];
    let response = await initialRequest;
    allItems.push(...(response.value || []));

    while (response["@odata.nextLink"]) {
        try {
            response = await client.api(response["@odata.nextLink"]).get();
            allItems.push(...(response.value || []));
        } catch (error) {
            if (error.statusCode === 429) {
                const retryAfter = parseInt(error.headers?.["retry-after"] || "10", 10);
                console.warn(`Throttled. Retry nach ${retryAfter}s...`);
                await new Promise(r => setTimeout(r, retryAfter * 1000));
                // Letzte Anfrage wiederholen
                response = await client.api(response["@odata.nextLink"]).get();
                allItems.push(...(response.value || []));
            } else {
                throw error;
            }
        }
    }
    return allItems;
}

// Alle Benutzer eines Tenants (paginiert)
const allUsers = await getAllPages(
    client,
    client.api("/users")
        .select("id,displayName,userPrincipalName")
        .top(999)
        .get()
);
console.log(`Gesamt: ${allUsers.length} Benutzer`);

using Microsoft.Graph.Models.ExternalConnectors;

// 1. Connector erstellen
var connector = new ExternalConnection
{
    Id          = "contosoproducts",
    Name        = "Contoso Produktkatalog",
    Description = "Produkte aus dem internen ERP-System",
    ActivitySettings = new ActivitySettings
    {
        UrlToItemResolvers = new List<UrlToItemResolverBase>
        {
            new ItemIdResolver
            {
                UrlMatchInfo = new UrlMatchInfo
                {
                    BaseUrls  = new List<string> { "https://erp.contoso.com" },
                    UrlPattern = "/products/(?<id>[^/]+)"
                },
                ItemId = "{id}"
            }
        }
    }
};
var created = await graphClient.External.Connections.PostAsync(connector);

// 2. Schema registrieren
var schema = new Schema
{
    BaseType   = "microsoft.graph.externalItem",
    Properties = new List<Property>
    {
        new() { Name = "productId",   Type = PropertyType.String,  IsQueryable = true,  IsSearchable = false, IsRetrievable = true },
        new() { Name = "title",       Type = PropertyType.String,  IsQueryable = true,  IsSearchable = true,  IsRetrievable = true },
        new() { Name = "description", Type = PropertyType.String,  IsQueryable = false, IsSearchable = true,  IsRetrievable = true },
        new() { Name = "price",       Type = PropertyType.Double,  IsQueryable = true,  IsSearchable = false, IsRetrievable = true }
    }
};
await graphClient.External.Connections["contosoproducts"].Schema.PatchAsync(schema);

// 3. Elemente einbringen
var item = new ExternalItem
{
    Id         = "product-001",
    Properties = new Properties { AdditionalData = new Dictionary<string, object>
    {
        ["productId"]   = "P-001",
        ["title"]       = "Widget Pro 3000",
        ["description"] = "Hochleistungs-Widget für industrielle Anwendungen",
        ["price"]       = 299.99
    }},
    Content = new ExternalItemContent
    {
        Type  = ExternalItemContentType.Text,
        Value = "Widget Pro 3000 – Hochleistungs-Widget mit 3-Jahres-Garantie."
    },
    Acl = new List<Acl>
    {
        new() { Type = AclType.Everyone, Value = "everyone", AccessType = AccessType.Grant }
    }
};
await graphClient.External.Connections["contosoproducts"]
    .Items["product-001"].PutAsync(item);

<!-- CDN-Einbindung -->
<script type="module"
    src="https://unpkg.com/@microsoft/mgt@4/dist/bundle/mgt-loader.js">
</script>

<!-- MSAL2-Provider konfigurieren -->
<mgt-msal2-provider
    client-id="YOUR_CLIENT_ID"
    login-type="popup"
    scopes="User.Read,Calendars.Read,Files.Read">
</mgt-msal2-provider>

<!-- Anmelde-Button -->
<mgt-login></mgt-login>

<!-- Aktueller Benutzer als Karte -->
<mgt-person person-query="me" view="twolines"></mgt-person>

<!-- Personen-Auswahl -->
<mgt-people-picker
    type="person,group"
    group-id="TEAM_GROUP_ID">
</mgt-people-picker>

<!-- Kalender-Agenda (nächste 7 Tage) -->
<mgt-agenda days="7" event-query="/me/calendarView"></mgt-agenda>

<!-- OneDrive Datei-Browser -->
<mgt-file-list></mgt-file-list>

<!-- Toolkit in SPFx / Teams (TypeScript) -->
<script type="module">
import { Providers, TeamsProvider } from "@microsoft/mgt";
import { TeamsMsal2Provider }       from "@microsoft/mgt-teams-msal2-provider";

// Teams-Context-Provider
Providers.globalProvider = new TeamsMsal2Provider({
    clientId: "YOUR_CLIENT_ID",
    scopes:   ["User.Read", "Calendars.Read"]
});

// Programmatischer Zugriff auf Graph via Toolkit-Provider
const provider = Providers.globalProvider;
const token    = await provider.getAccessToken({ scopes: ["User.Read"] });
const response = await fetch("https://graph.microsoft.com/v1.0/me", {
    headers: { Authorization: `Bearer ${token}` }
});
const me = await response.json();
console.log(me.displayName);
</script>

Install-Module Microsoft.Graph -Scope CurrentUser -Force

# App-only Authentifizierung mit Client Credentials
Connect-MgGraph -TenantId $tenantId -ClientId $appId -ClientSecretCredential `
    (New-Object System.Management.Automation.PSCredential($appId,
        (ConvertTo-SecureString $secret -AsPlainText -Force)))

# Alternativ: Zertifikat
Connect-MgGraph -TenantId $tenantId -ClientId $appId -CertificateThumbprint $thumbprint

# Benutzer mit ConsistencyLevel-Header und $count abrufen
$users = Invoke-MgGraphRequest -Method GET `
    -Uri "https://graph.microsoft.com/v1.0/users?`$count=true&`$top=999&`$select=id,displayName,userPrincipalName" `
    -Headers @{ "ConsistencyLevel" = "eventual" }
Write-Host "Gesamt: $($users.'@odata.count') Benutzer"

# Batch-Anfrage über Invoke-MgGraphRequest
$batchBody = @{
    requests = @(
        @{ id = "1"; method = "GET"; url = "/users/alice@contoso.com" },
        @{ id = "2"; method = "GET"; url = "/users/bob@contoso.com" }
    )
} | ConvertTo-Json -Depth 5

$batchResponse = Invoke-MgGraphRequest -Method POST `
    -Uri "https://graph.microsoft.com/v1.0/`$batch" `
    -Body $batchBody -ContentType "application/json"

$batchResponse.responses | ForEach-Object {
    Write-Host "Id: $($_.id), Status: $($_.status), Name: $($_.body.displayName)"
}

# Delta für Gruppen
$deltaResponse = Invoke-MgGraphRequest -Method GET `
    -Uri "https://graph.microsoft.com/v1.0/groups/delta?`$select=displayName,members"

# Delta-Token extrahieren und speichern
$deltaLink = $deltaResponse.'@odata.deltaLink'
Write-Host "Delta-Token gespeichert: $($deltaLink.Length) Zeichen"

Disconnect-MgGraph