Создание приложений Java с применением Microsoft Graph

Статья
Developer (Начальный уровень)
28 мин до завершения

В этом руководстве описано, как создать консольное приложение Java, которое использует API Graph Майкрософт для доступа к данным от имени пользователя.

Примечание.

Сведения о том, как использовать Microsoft Graph для доступа к данным с помощью проверки подлинности только для приложений, см. в этом руководстве по проверке подлинности только для приложений.

В этом руководстве описан порядок выполнения перечисленных ниже задач.

Совет

Вместо этого вы можете скачать готовый код с помощью средства быстрого запуска , которое автоматизирует регистрацию и настройку приложений. Скачанный код работает без каких-либо изменений.

Вы также можете скачать или клонировать репозиторий GitHub и следовать инструкциям в файле README, чтобы зарегистрировать приложение и настроить проект.

Предварительные требования

Прежде чем приступить к работе с этим руководством, на компьютере разработки должны быть установлены Пакет средств разработки Java SE (JDK) и Gradle .

У вас также должна быть личная учетная запись Майкрософт с почтовым ящиком на Outlook.com либо рабочая или учебная учетная запись Майкрософт. Если у вас нет учетной записи Майкрософт, можно получить бесплатную учетную запись несколькими способами:

Вы можете зарегистрироваться для получения новой личной учетной записи Майкрософт.
Вы можете зарегистрироваться в программе разработчиков Microsoft 365 , чтобы получить бесплатную подписку На Microsoft 365.

Примечание.

Это руководство было написано с openJDK версии 17.0.2 и Gradle 7.4.2. Действия, описанные в этом руководстве, могут работать с другими версиями, но не были протестированы.

Регистрация приложения на портале

Осталось 27 мин

В этом упражнении вы зарегистрируете новое приложение в Azure Active Directory, чтобы включить проверку подлинности пользователей. Вы можете зарегистрировать приложение с помощью Центра администрирования Azure Active Directory или с помощью пакета SDK Для Microsoft Graph PowerShell.

Регистрация приложения для проверки подлинности пользователей

В этом разделе вы зарегистрируете приложение, которое будет поддерживать проверку подлинности пользователей с помощью потока кода устройства.

Центр администрирования Azure AD
PowerShell

Откройте браузер и перейдите в Центр администрирования Azure Active Directory и войдите с помощью личной учетной записи (т.е. учетной записи Майкрософт) или рабочей или учебной учетной записи.
Выберите Azure Active Directory на панели навигации слева, затем выберите Регистрация приложений в разделе Управление.
Выберите Новая регистрация. Введите имя приложения, например Java Graph Tutorial.

Задайте поддерживаемые типы учетных записей . Доступны следующие варианты:

Вариант	Кто может выполнить вход?
Учетные записи только в этом каталоге организации	Только пользователи в организации Microsoft 365
Учетные записи в любом каталоге организации	Пользователи в любой организации Microsoft 365 (рабочие или учебные учетные записи)
Учетные записи в любом каталоге организации... и личные учетные записи Майкрософт	Пользователи в любой организации Microsoft 365 (рабочие или учебные учетные записи) и личные учетные записи Майкрософт

Оставьте поле URI перенаправления пустым.
Нажмите Зарегистрировать. На странице "Обзор " приложения скопируйте значение идентификатора приложения (клиента) и сохраните его. Оно понадобится на следующем шаге. Если вы выбрали Учетные записи в этом каталоге организации только для поддерживаемых типов учетных записей, скопируйте идентификатор каталога (клиента) и сохраните его.
Выберите пункт Проверка подлинности в разделе Управление. Найдите раздел Дополнительные параметры и установите переключатель Разрешить общедоступные клиентские потоки на Да, а затем нажмите кнопку Сохранить.

Чтобы использовать PowerShell, вам потребуется пакет SDK Для Microsoft Graph PowerShell. Если у вас его нет, инструкции по установке см. в разделе Установка пакета SDK Для Microsoft Graph PowerShell .

Важно!

Для сценария PowerShell требуется рабочая или учебная учетная запись с администратором приложений, администратором облачных приложений или ролью глобальный администратор. Если ваша учетная запись имеет роль разработчика приложений, вы можете зарегистрироваться в Центре администрирования Azure AD.

Создайте файл с именем RegisterAppForUserAuth.ps1 и добавьте следующий код.

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

Сохраните файл.
Откройте PowerShell и измените текущий каталог на расположение RegisterAppForUserAuth.ps1.

Выполните следующую команду, заменив <значение> аудитории нужным значением (см. таблицу ниже).

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

Значение SignInAudience	Кто может выполнить вход?
`AzureADMyOrg`	Только пользователи в организации Microsoft 365
`AzureADMultipleOrgs`	Пользователи в любой организации Microsoft 365 (рабочие или учебные учетные записи)
`AzureADandPersonalMicrosoftAccount`	Пользователи в любой организации Microsoft 365 (рабочие или учебные учетные записи) и личные учетные записи Майкрософт
`PersonalMicrosoftAccount`	Только личные учетные записи Майкрософт

Следуйте запросу, чтобы открыть https://microsoft.com/devicelogin в браузере, введите предоставленный код и завершите процесс проверки подлинности.
Скопируйте значения идентификатора клиента и проверки подлинности из выходных данных скрипта. Эти значения потребуются на следующем шаге.
```
SUCCESS
Client ID: 2fb1652f-a9a0-4db9-b220-b224b8d9d38b
Auth tenant: common
```

Примечание.

Обратите внимание, что вы не настроили разрешения Microsoft Graph для регистрации приложения. Это связано с тем, что в примере будет использоваться динамическое согласие для запроса определенных разрешений для проверки подлинности пользователя.

Создание консольного приложения Java

Осталось 25 мин

В этом разделе вы создадите базовое консольное приложение Java.

Откройте интерфейс командной строки (CLI) в каталоге, в котором вы хотите создать проект. Выполните следующую команду, чтобы создать проект Gradle.
```
gradle init --dsl groovy --test-framework junit --type java-application --project-name graphtutorial --package graphtutorial
```
После создания проекта убедитесь, что он работает, выполнив следующую команду, чтобы запустить приложение в интерфейсе командной строки.
```
./gradlew --console plain run
```
Если это работает, приложение должно вывести .Hello World.

Установка зависимостей

Прежде чем переходить дальше, добавьте некоторые дополнительные зависимости, которые будут использоваться позже.

Клиентская библиотека удостоверений Azure для Java для проверки подлинности пользователя и получения маркеров доступа.
Пакет SDK Microsoft Graph для Java для выполнения вызовов к Microsoft Graph.

Откройте ./app/build.gradle. Обновите раздел, dependencies чтобы добавить эти зависимости.

dependencies {
    // Use JUnit test framework.
    testImplementation 'junit:junit:4.13.2'

    // This dependency is used by the application.
    implementation 'com.google.guava:guava:31.1-jre'
    implementation 'com.azure:azure-identity:1.7.1'
    implementation 'com.microsoft.graph:microsoft-graph:5.42.0'
}

Добавьте следующий код в конец ./app/build.gradle.
```
run {
    standardInput = System.in
}
```
При следующей сборке проекта Gradle загрузит эти зависимости.

Загрузка параметров приложения

В этом разделе вы добавите в проект сведения о регистрации приложения.

Создайте каталог с именем graphtutorial в каталоге ./app/src/main/resources .
Создайте новый файл в каталоге ./app/src/main/resources/graphtutorial с именем oAuth.properties и добавьте в этот файл следующий текст.
```
app.clientId=YOUR_CLIENT_ID_HERE
app.tenantId=common
app.graphUserScopes=user.read,mail.read,mail.send
```

Обновите значения в соответствии со следующей таблицей.

Параметр	Значение
`app.clientId`	Идентификатор клиента для регистрации приложения
`app.tenantId`	Если вы выбрали параметр, разрешать вход только пользователям в вашей организации, измените это значение на идентификатор клиента. В противном случае оставьте значение `common`.

Важно!

Если вы используете систему управления версиями, например Git, то теперь лучше исключить файл oAuth.properties из системы управления версиями, чтобы избежать случайной утечки идентификатора приложения.

Проектирование приложения

В этом разделе вы создадите простое меню на основе консоли.

Откройте ./app/src/main/java/graphtutorial/App.java и добавьте следующие import инструкции.

package graphtutorial;

import java.io.IOException;
import java.time.ZoneId;
import java.time.format.DateTimeFormatter;
import java.time.format.FormatStyle;
import java.util.InputMismatchException;
import java.util.Properties;
import java.util.Scanner;

import com.microsoft.graph.models.Message;
import com.microsoft.graph.models.User;
import com.microsoft.graph.requests.MessageCollectionPage;

Замените имеющуюся функцию main указанным ниже кодом.

public static void main(String[] args) {
    System.out.println("Java Graph Tutorial");
    System.out.println();

    final Properties oAuthProperties = new Properties();
    try {
        oAuthProperties.load(App.class.getResourceAsStream("oAuth.properties"));
    } catch (IOException e) {
        System.out.println("Unable to read OAuth configuration. Make sure you have a properly formatted oAuth.properties file. See README for details.");
        return;
    }

    initializeGraph(oAuthProperties);

    greetUser();

    Scanner input = new Scanner(System.in);

    int choice = -1;

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

        try {
            choice = input.nextInt();
        } catch (InputMismatchException ex) {
            // Skip over non-integer input
        }

        input.nextLine();

        // Process user choice
        switch(choice) {
            case 0:
                // Exit the program
                System.out.println("Goodbye...");
                break;
            case 1:
                // Display access token
                displayAccessToken();
                break;
            case 2:
                // List emails from user's inbox
                listInbox();
                break;
            case 3:
                // Send an email message
                sendMail();
                break;
            case 4:
                // Run any Graph code
                makeGraphCall();
                break;
            default:
                System.out.println("Invalid choice");
        }
    }

    input.close();
}

Добавьте следующие методы-заполнители в конец файла. Вы будете реализовывать их на последующих шагах.

private static void initializeGraph(Properties properties) {
    // TODO
}

private static void greetUser() {
    // TODO
}

private static void displayAccessToken() {
    // TODO
}

private static void listInbox() {
    // TODO
}

private static void sendMail() {
    // TODO
}

private static void makeGraphCall() {
    // TODO
}

Это реализует базовое меню и считывает выбор пользователя из командной строки.

Удалите ./app/src/test/java/graphtutorial/AppTest.java.

Добавление проверки подлинности пользователя

Осталось 19 мин

В этом разделе вы расширите приложение из предыдущего упражнения для поддержки проверки подлинности с помощью Azure AD. Это необходимо для получения необходимого маркера доступа OAuth для вызова Microsoft Graph. На этом шаге вы интегрируете клиентную библиотеку удостоверений Azure для Java в приложение и настроите проверку подлинности для пакета SDK Microsoft Graph для Java.

Библиотека удостоверений Azure предоставляет ряд классов, которые реализуют потоки маркеров TokenCredential OAuth2. Клиентская библиотека Microsoft Graph использует эти классы для проверки подлинности вызовов Microsoft Graph.

Настройка клиента Graph для проверки подлинности пользователей

В этом разделе вы будете DeviceCodeCredential использовать класс для запроса маркера доступа с помощью потока кода устройства.

Создайте новый файл в каталоге ./app/src/main/java/graphtutorialс именем Graph.java и добавьте в этот файл следующий код.

package graphtutorial;

import java.util.Arrays;
import java.util.List;
import java.util.Properties;
import java.util.function.Consumer;

import com.azure.core.credential.AccessToken;
import com.azure.core.credential.TokenRequestContext;
import com.azure.identity.DeviceCodeCredential;
import com.azure.identity.DeviceCodeCredentialBuilder;
import com.azure.identity.DeviceCodeInfo;
import com.microsoft.graph.authentication.TokenCredentialAuthProvider;
import com.microsoft.graph.models.BodyType;
import com.microsoft.graph.models.EmailAddress;
import com.microsoft.graph.models.ItemBody;
import com.microsoft.graph.models.Message;
import com.microsoft.graph.models.Recipient;
import com.microsoft.graph.models.User;
import com.microsoft.graph.models.UserSendMailParameterSet;
import com.microsoft.graph.requests.GraphServiceClient;
import com.microsoft.graph.requests.MessageCollectionPage;

import okhttp3.Request;

Добавьте пустое определение класса Graph .
```
public class Graph {
}
```

Добавьте следующий код в класс Graph.

private static Properties _properties;
private static DeviceCodeCredential _deviceCodeCredential;
private static GraphServiceClient<Request> _userClient;

public static void initializeGraphForUserAuth(Properties properties, Consumer<DeviceCodeInfo> challenge) throws Exception {
    // Ensure properties isn't null
    if (properties == null) {
        throw new Exception("Properties cannot be null");
    }

    _properties = properties;

    final String clientId = properties.getProperty("app.clientId");
    final String tenantId = properties.getProperty("app.tenantId");
    final List<String> graphUserScopes = Arrays
        .asList(properties.getProperty("app.graphUserScopes").split(","));

    _deviceCodeCredential = new DeviceCodeCredentialBuilder()
        .clientId(clientId)
        .tenantId(tenantId)
        .challengeConsumer(challenge)
        .build();

    final TokenCredentialAuthProvider authProvider =
        new TokenCredentialAuthProvider(graphUserScopes, _deviceCodeCredential);

    _userClient = GraphServiceClient.builder()
        .authenticationProvider(authProvider)
        .buildClient();
}

Замените пустую initializeGraph функцию в App.java следующим кодом.

private static void initializeGraph(Properties properties) {
    try {
        Graph.initializeGraphForUserAuth(properties,
            challenge -> System.out.println(challenge.getMessage()));
    } catch (Exception e)
    {
        System.out.println("Error initializing Graph for user auth");
        System.out.println(e.getMessage());
    }
}

Этот код объявляет два частных свойства: DeviceCodeCredential объект и GraphServiceClient объект . Функция InitializeGraphForUserAuth создает новый экземпляр DeviceCodeCredential, а затем использует его для создания нового экземпляра GraphServiceClient. Каждый раз, когда вызов API выполняется в Microsoft Graph через _userClient, он будет использовать предоставленные учетные данные для получения маркера доступа.

Тестирование DeviceCodeCredential

Затем добавьте код для получения маркера доступа из DeviceCodeCredential.

Добавьте к классу Graph следующую функцию:

public static String getUserToken() throws Exception {
    // Ensure credential isn't null
    if (_deviceCodeCredential == null) {
        throw new Exception("Graph has not been initialized for user auth");
    }

    final String[] graphUserScopes = _properties.getProperty("app.graphUserScopes").split(",");

    final TokenRequestContext context = new TokenRequestContext();
    context.addScopes(graphUserScopes);

    final AccessToken token = _deviceCodeCredential.getToken(context).block();
    return token.getToken();
}

Замените пустую displayAccessToken функцию в App.java следующим кодом.

private static void displayAccessToken() {
    try {
        final String accessToken = Graph.getUserToken();
        System.out.println("Access token: " + accessToken);
    } catch (Exception e) {
        System.out.println("Error getting access token");
        System.out.println(e.getMessage());
    }
}

Выполните сборку и запуск приложения. Введите 1 при появлении запроса на выбор параметра. Приложение отображает URL-адрес и код устройства.

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

Откройте браузер и перейдите по url-адресу. Введите предоставленный код и войдите в систему.

Важно!

Помните о всех существующих учетных записях Microsoft 365, которые вошли в браузер при просмотре страницы https://microsoft.com/devicelogin. Используйте функции браузера, такие как профили, гостевой режим или частный режим, чтобы проверить подлинность в качестве учетной записи, которую вы планируете использовать для тестирования.
После завершения вернитесь к приложению, чтобы увидеть маркер доступа.

Совет

Только для проверки и отладки можно декодировать маркеры доступа пользователей (только для рабочих или учебных учетных записей) с помощью средства синтаксического анализа токенов Майкрософт в сети по адресу https://jwt.ms. Это может быть полезно, если при вызове Microsoft Graph возникают ошибки маркера. Например, убедитесь, что scp утверждение в маркере содержит ожидаемые области разрешений Microsoft Graph.

Получение пользователя

Осталось 14 мин

В этом разделе вы включите Microsoft Graph в приложение. Для этого приложения вы будете использовать клиентную библиотеку Java Microsoft Graph для выполнения вызовов к Microsoft Graph.

Откройте Graph.java и добавьте следующую функцию в класс Graph .

public static User getUser() throws Exception {
    // Ensure client isn't null
    if (_userClient == null) {
        throw new Exception("Graph has not been initialized for user auth");
    }

    return _userClient.me()
        .buildRequest()
        .select("displayName,mail,userPrincipalName")
        .get();
}

Замените пустую greetUser функцию в App.java следующим кодом.

private static void greetUser() {
    try {
        final User user = Graph.getUser();
        // For Work/school accounts, email is in mail property
        // Personal accounts, email is in userPrincipalName
        final String email = user.mail == null ? user.userPrincipalName : user.mail;
        System.out.println("Hello, " + user.displayName + "!");
        System.out.println("Email: " + email);
    } catch (Exception e) {
        System.out.println("Error getting user");
        System.out.println(e.getMessage());
    }
}

Если вы запустите приложение сейчас, после входа в приложение будет приветствовать вас по имени.

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

Описание кода

Рассмотрим код в greetUser функции. Это всего несколько строк, но есть некоторые ключевые детали, которые следует обратить внимание.

Доступ к "мне"

Функция использует построитель _userClient.me запросов, который создает запрос к API get user . Этот API доступен двумя способами:

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

В этом случае код вызывает конечную точку GET /me API. Это ярлык, который позволяет получить пользователя, прошедшего проверку подлинности, не зная его идентификатора пользователя.

Примечание.

GET /me Так как конечная точка API получает пользователя, прошедшего проверку подлинности, она доступна только для приложений, использующих проверку подлинности пользователей. Приложения для проверки подлинности только для приложений не могут получить доступ к этой конечной точке.

Запрос определенных свойств

Функция использует select метод в запросе для указания набора необходимых ей свойств. При этом параметр запроса $select добавляется в вызов API.

Строго типизированный тип возвращаемого значения

Функция возвращает объект, com.microsoft.graph.models.User десериализованный из ответа JSON из API. Так как код использует select, только запрошенные свойства будут иметь значения в возвращаемом объекте User . Все остальные свойства будут иметь значения по умолчанию.

Перечисление папки "Входящие"

Осталось 11 мин

В этом разделе вы добавите возможность выводить список сообщений в папке "Входящие" пользователя.

Откройте Graph.java и добавьте следующую функцию в класс Graph .

public static MessageCollectionPage getInbox() throws Exception {
    // Ensure client isn't null
    if (_userClient == null) {
        throw new Exception("Graph has not been initialized for user auth");
    }

    return _userClient.me()
        .mailFolders("inbox")
        .messages()
        .buildRequest()
        .select("from,isRead,receivedDateTime,subject")
        .top(25)
        .orderBy("receivedDateTime DESC")
        .get();
}

Замените пустую listInbox функцию в App.java следующим кодом.

private static void listInbox() {
    try {
        final MessageCollectionPage messages = Graph.getInbox();

        // Output each message's details
        for (Message message: messages.getCurrentPage()) {
            System.out.println("Message: " + message.subject);
            System.out.println("  From: " + message.from.emailAddress.name);
            System.out.println("  Status: " + (message.isRead ? "Read" : "Unread"));
            System.out.println("  Received: " + message.receivedDateTime
                // Values are returned in UTC, convert to local time zone
                .atZoneSameInstant(ZoneId.systemDefault()).toLocalDateTime()
                .format(DateTimeFormatter.ofLocalizedDateTime(FormatStyle.SHORT)));
        }

        final Boolean moreMessagesAvailable = messages.getNextPage() != null;
        System.out.println("\nMore messages available? " + moreMessagesAvailable);
    } catch (Exception e) {
        System.out.println("Error getting inbox");
        System.out.println(e.getMessage());
    }
}

Запустите приложение, войдите в систему и выберите вариант 2, чтобы получить список папки "Входящие".

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: 12/30/2021, 4:54:54 AM
Message: Employee Initiative Thoughts
  From: Patti Fernandez
  Status: Read
  Received: 12/28/2021, 5:01:10 PM
Message: Voice Mail (11 seconds)
  From: Alex Wilber
  Status: Unread
  Received: 12/28/2021, 5:00:46 PM
Message: Our Spring Blog Update
  From: Alex Wilber
  Status: Unread
  Received: 12/28/2021, 4:49:46 PM
Message: Atlanta Flight Reservation
  From: Alex Wilber
  Status: Unread
  Received: 12/28/2021, 4:35:42 PM
Message: Atlanta Trip Itinerary - down time
  From: Alex Wilber
  Status: Unread
  Received: 12/28/2021, 4:22:04 PM

...

More messages available? true

Описание кода

Рассмотрим код в getInbox функции.

Доступ к известным почтовым папкам

Функция использует построитель _userClient.me().mailFolders("inbox").messages() запросов, который создает запрос к API списка сообщений . Так как он включает построитель mailFolders("inbox") запросов, API будет возвращать только сообщения в папке запрошенной почты. В этом случае, так как папка "Входящие" является хорошо известной папкой по умолчанию внутри почтового ящика пользователя, она доступна по известному имени. Доступ к папкам, не используемым по умолчанию, можно получить таким же образом, заменив известное имя свойством идентификатора почтовой папки. Дополнительные сведения о доступных известных именах папок см. в разделе Тип ресурса mailFolder.

Доступ к коллекции

getUser В отличие от функции из предыдущего раздела, которая возвращает один объект, этот метод возвращает коллекцию сообщений. Большинство API в Microsoft Graph, возвращающих коллекцию, не возвращают все доступные результаты в одном ответе. Вместо этого они используют разбиение на страницы , чтобы вернуть часть результатов, предоставляя метод для клиентов, чтобы запросить следующую "страницу".

Размеры страниц по умолчанию

API, использующие разбиение на страницы, реализуют размер страницы по умолчанию. Для сообщений значение по умолчанию — 10. Клиенты могут запрашивать больше (или меньше) с помощью параметра запроса $top . В getInboxэто выполняется с помощью .top(25) метода .

Примечание.

Значение, передаваемое в .top() , является верхней границей, а не явным числом. API возвращает количество сообщений до указанного значения.

Получение последующих страниц

Если на сервере доступно больше результатов, ответы коллекции содержат @odata.nextLink свойство с URL-адресом API для доступа к следующей странице. Клиентская библиотека Java предоставляет этот метод в getNextPage качестве метода для объектов страницы коллекции. Если этот метод возвращает значение, отличное от NULL, доступны дополнительные результаты.

Сортировка коллекций

Функция использует orderBy метод в запросе для запроса результатов, отсортированных по времени получения сообщения (receivedDateTime свойство). Он включает ключевое DESC слово, чтобы сообщения, полученные в последнее время, отображались первыми. При этом параметр запроса $orderby добавляется в вызов API.

Отправка почты

Осталось 8 мин

В этом разделе вы добавите возможность отправки сообщения электронной почты в качестве пользователя, прошедшего проверку подлинности.

Откройте Graph.java и добавьте следующую функцию в класс Graph .

public static void sendMail(String subject, String body, String recipient) throws Exception {
    // Ensure client isn't null
    if (_userClient == null) {
        throw new Exception("Graph has not been initialized for user auth");
    }

    // Create a new message
    final Message message = new Message();
    message.subject = subject;
    message.body = new ItemBody();
    message.body.content = body;
    message.body.contentType = BodyType.TEXT;

    final Recipient toRecipient = new Recipient();
    toRecipient.emailAddress = new EmailAddress();
    toRecipient.emailAddress.address = recipient;
    message.toRecipients = List.of(toRecipient);

    // Send the message
    _userClient.me()
        .sendMail(UserSendMailParameterSet.newBuilder()
            .withMessage(message)
            .build())
        .buildRequest()
        .post();
}

Замените пустую sendMail функцию в App.java следующим кодом.

private static void sendMail() {
    try {
        // Send mail to the signed-in user
        // Get the user for their email address
        final User user = Graph.getUser();
        final String email = user.mail == null ? user.userPrincipalName : user.mail;

        Graph.sendMail("Testing Microsoft Graph", "Hello world!", email);
        System.out.println("\nMail sent.");
    } catch (Exception e) {
        System.out.println("Error sending mail");
        System.out.println(e.getMessage());
    }
}

Запустите приложение, войдите в систему и выберите вариант 3, чтобы отправить себе сообщение электронной почты.
```
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.
```
Примечание.

Если вы тестируете с помощью клиента разработчика из Программы разработчика Microsoft 365, отправленное сообщение электронной почты может не быть доставлено, и вы можете получить отчет о недоставки. Если это случится с вами, обратитесь в службу поддержки через Центр администрирования Microsoft 365.
Чтобы убедиться, что сообщение получено, выберите вариант 2, чтобы получить список папки "Входящие".

Описание кода

Рассмотрим код в sendMail функции.

Отправка почты

Функция использует построитель _userClient.me().sendMail() запросов, который создает запрос к API отправки почты . Построитель запросов принимает объект, UserSendMailParameterSet содержащий сообщение для отправки.

Создание объектов

В отличие от предыдущих вызовов Microsoft Graph, которые считывают только данные, этот вызов создает данные. Для этого с помощью клиентской библиотеки создайте экземпляр класса , представляющего данные (в данном случае ) com.microsoft.graph.models.Messageс помощью ключевого new слова , задайте нужные свойства, а затем отправьте его в вызове API. Так как вызов отправляет данные, post вместо используется getметод .

Необязательно: добавление собственного кода

Осталось 5 мин

В этом разделе вы добавите в приложение собственные возможности Microsoft Graph. Это может быть фрагмент кода из документации Microsoft Graph или обозревателя Graph или созданный вами код. Этот раздел является необязательным.

Обновите приложение

Откройте Graph.java и добавьте следующую функцию в класс Graph .
```
public static void makeGraphCall() {
    // INSERT YOUR CODE HERE
}
```

Замените пустую MakeGraphCallAsync функцию в App.java следующим кодом.

private static void makeGraphCall() {
    try {
        Graph.makeGraphCall();
    } catch (Exception e) {
        System.out.println("Error making Graph call");
        System.out.println(e.getMessage());
    }
}

Выбор API

Найдите API в Microsoft Graph, который вы хотите попробовать. Например, API создания событий . Вы можете использовать один из примеров в документации по API или настроить запрос API в Graph Explorer и использовать созданный фрагмент кода.

Настройка разрешений

Ознакомьтесь с разделом Разрешения справочной документации по выбранному API, чтобы узнать, какие методы проверки подлинности поддерживаются. Некоторые API не поддерживают только приложения или личные учетные записи Майкрософт, например.

Чтобы вызвать API с проверкой подлинности пользователя (если API поддерживает проверку подлинности пользователя (делегированная), добавьте требуемую область разрешений в oAuth.properties.
Чтобы вызвать API с проверкой подлинности только для приложений, ознакомьтесь с руководством по проверке подлинности только для приложений .

Добавление кода

Скопируйте код в функцию makeGraphCallAsync в Graph.java. Если вы копируете фрагмент из документации или обозревателя Graph, обязательно переименуйте GraphServiceClient_userClientв .

Создание приложений Java с применением Microsoft Graph

Предварительные требования

Регистрация приложения на портале

Регистрация приложения для проверки подлинности пользователей

Создание консольного приложения Java

Установка зависимостей

Загрузка параметров приложения

Проектирование приложения

Добавление проверки подлинности пользователя

Настройка клиента Graph для проверки подлинности пользователей

Тестирование DeviceCodeCredential

Получение пользователя

Описание кода

Доступ к "мне"

Запрос определенных свойств

Строго типизированный тип возвращаемого значения

Перечисление папки "Входящие"

Описание кода

Доступ к известным почтовым папкам

Доступ к коллекции

Размеры страниц по умолчанию

Получение последующих страниц

Сортировка коллекций

Отправка почты

Описание кода

Отправка почты

Создание объектов

Необязательно: добавление собственного кода

Обновите приложение

Выбор API

Настройка разрешений

Добавление кода

Поздравляем!

Примеры Java