Создание приложений Go с помощью Microsoft Graph

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

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

Примечание.

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

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

Совет

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

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

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

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

У вас также должна быть рабочая или учебная учетная запись Майкрософт с почтовым ящиком Exchange Online. Если у вас нет клиента Microsoft 365, вы можете претендовать на него в рамках Программы разработчиков Microsoft 365. Дополнительные сведения см. в разделе Вопросы и ответы. Кроме того, вы можете зарегистрироваться для получения бесплатной пробной версии на 1 месяц или приобрести план Microsoft 365.

Примечание.

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

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

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

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

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

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

Центр администрирования Microsoft Entra
PowerShell

Откройте браузер и перейдите в Центр администрирования Microsoft Entra и войдите с помощью учетной записи глобального администратора.
Выберите Идентификатор Microsoft Entra в области навигации слева, разверните узел Удостоверение, Приложения, а затем выберите Регистрация приложений.
Выберите Новая регистрация. Введите имя приложения, например Graph User Auth Tutorial.

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

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

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

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

Важно!

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

Создайте файл с именем 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 | 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"
}

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

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

.\RegisterAppForUserAuth.ps1 -AppName "Graph User Auth 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 для регистрации приложения. Это связано с тем, что в примере используется динамическое согласие для запроса определенных разрешений для проверки подлинности пользователя.

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

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

Начните с инициализации нового модуля Go с помощью Go CLI. Откройте интерфейс командной строки (CLI) в каталоге, в котором вы хотите создать проект. Выполните следующую команду.

go mod init graphtutorial

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

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

Клиентский модуль удостоверений Azure для Go для проверки подлинности пользователя и получения маркеров доступа.
Пакет SDK Microsoft Graph для Go для выполнения вызовов Microsoft Graph.
GoDotEnv для чтения переменных среды из ENV-файлов.

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

go get github.com/Azure/azure-sdk-for-go/sdk/azidentity
go get github.com/microsoftgraph/msgraph-sdk-go
go get github.com/joho/godotenv

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

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

Создайте файл в том же каталоге, что и go.mod с именем .env , и добавьте следующий код.
```
CLIENT_ID=YOUR_CLIENT_ID_HERE
TENANT_ID=common
GRAPH_USER_SCOPES=user.read,mail.read,mail.send
```

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

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

Совет

При необходимости эти значения можно задать в отдельном файле с именем .env.local.

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

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

Создайте новый каталог в том же каталоге, что и go.mod с именем graphhelper.

Добавьте новый файл в каталог graphhelper с именем graphhelper.go и добавьте следующий код.

package graphhelper

import (
    "context"
    "fmt"
    "os"
    "strings"

    "github.com/Azure/azure-sdk-for-go/sdk/azcore/policy"
    "github.com/Azure/azure-sdk-for-go/sdk/azidentity"
    auth "github.com/microsoft/kiota-authentication-azure-go"
    msgraphsdk "github.com/microsoftgraph/msgraph-sdk-go"
    "github.com/microsoftgraph/msgraph-sdk-go/models"
    "github.com/microsoftgraph/msgraph-sdk-go/users"
)

type GraphHelper struct {
    deviceCodeCredential *azidentity.DeviceCodeCredential
    userClient           *msgraphsdk.GraphServiceClient
    graphUserScopes      []string
}

func NewGraphHelper() *GraphHelper {
    g := &GraphHelper{}
    return g
}

При этом создается базовый тип GraphHelper , который будет расширен в последующих разделах для использования Microsoft Graph.

Создайте файл в том же каталоге, что и go.mod с именем graphtutorial.go. Добавьте в него указанный ниже код.

package main

import (
    "fmt"
    "graphtutorial/graphhelper"
    "log"
    "time"

    "github.com/joho/godotenv"
)

func main() {
    fmt.Println("Go Graph Tutorial")
    fmt.Println()

    // Load .env files
    // .env.local takes precedence (if present)
    godotenv.Load(".env.local")
    err := godotenv.Load()
    if err != nil {
        log.Fatal("Error loading .env")
    }

    graphHelper := graphhelper.NewGraphHelper()

    initializeGraph(graphHelper)

    greetUser(graphHelper)

    var choice int64 = -1

    for {
        fmt.Println("Please choose one of the following options:")
        fmt.Println("0. Exit")
        fmt.Println("1. Display access token")
        fmt.Println("2. List my inbox")
        fmt.Println("3. Send mail")
        fmt.Println("4. Make a Graph call")

        _, err = fmt.Scanf("%d", &choice)
        if err != nil {
            choice = -1
        }

        switch choice {
        case 0:
            // Exit the program
            fmt.Println("Goodbye...")
        case 1:
            // Display access token
            displayAccessToken(graphHelper)
        case 2:
            // List emails from user's inbox
            listInbox(graphHelper)
        case 3:
            // Send an email message
            sendMail(graphHelper)
        case 4:
            // Run any Graph code
            makeGraphCall(graphHelper)
        default:
            fmt.Println("Invalid choice! Please try again.")
        }

        if choice == 0 {
            break
        }
    }
}

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

func initializeGraph(graphHelper *graphhelper.GraphHelper) {
    // TODO
}

func greetUser(graphHelper *graphhelper.GraphHelper) {
    // TODO
}

func displayAccessToken(graphHelper *graphhelper.GraphHelper) {
    // TODO
}

func listInbox(graphHelper *graphhelper.GraphHelper) {
    // TODO
}

func sendMail(graphHelper *graphhelper.GraphHelper) {
    // TODO
}

func makeGraphCall(graphHelper *graphhelper.GraphHelper) {
    // TODO
}

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

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

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

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

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

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

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

Добавьте следующую функцию в ./graphhelper/graphhelper.go.

func (g *GraphHelper) InitializeGraphForUserAuth() error {
    clientId := os.Getenv("CLIENT_ID")
    tenantId := os.Getenv("TENANT_ID")
    scopes := os.Getenv("GRAPH_USER_SCOPES")
    g.graphUserScopes = strings.Split(scopes, ",")

    // Create the device code credential
    credential, err := azidentity.NewDeviceCodeCredential(&azidentity.DeviceCodeCredentialOptions{
        ClientID: clientId,
        TenantID: tenantId,
        UserPrompt: func(ctx context.Context, message azidentity.DeviceCodeMessage) error {
            fmt.Println(message.Message)
            return nil
        },
    })
    if err != nil {
        return err
    }

    g.deviceCodeCredential = credential

    // Create an auth provider using the credential
    authProvider, err := auth.NewAzureIdentityAuthenticationProviderWithScopes(credential, g.graphUserScopes)
    if err != nil {
        return err
    }

    // Create a request adapter using the auth provider
    adapter, err := msgraphsdk.NewGraphRequestAdapter(authProvider)
    if err != nil {
        return err
    }

    // Create a Graph client using request adapter
    client := msgraphsdk.NewGraphServiceClient(adapter)
    g.userClient = client

    return nil
}

Совет

Если вы используете goimports, некоторые модули, возможно, были автоматически удалены из инструкции import в graphhelper.go при сохранении. Возможно, потребуется повторно добавить модули для сборки.

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

func initializeGraph(graphHelper *graphhelper.GraphHelper) {
    err := graphHelper.InitializeGraphForUserAuth()
    if err != nil {
        log.Panicf("Error initializing Graph for user auth: %v\n", err)
    }
}

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

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

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

Добавьте следующую функцию в ./graphhelper/graphhelper.go.

func (g *GraphHelper) GetUserToken() (*string, error) {
    token, err := g.deviceCodeCredential.GetToken(context.Background(), policy.TokenRequestOptions{
        Scopes: g.graphUserScopes,
    })
    if err != nil {
        return nil, err
    }

    return &token.Token, nil
}

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

func displayAccessToken(graphHelper *graphhelper.GraphHelper) {
    token, err := graphHelper.GetUserToken()
    if err != nil {
        log.Panicf("Error getting user token: %v\n", err)
    }

    fmt.Printf("User token: %s", *token)
    fmt.Println()
}

Выполните сборку и запуск приложения, запустив go run graphtutorial. Введите 1 при появлении запроса на выбор параметра. Приложение отображает URL-адрес и код устройства.
```
Go 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.

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

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

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

Добавьте следующую функцию в ./graphhelper/graphhelper.go.

func (g *GraphHelper) GetUser() (models.Userable, error) {
    query := users.UserItemRequestBuilderGetQueryParameters{
        // Only request specific properties
        Select: []string{"displayName", "mail", "userPrincipalName"},
    }

    return g.userClient.Me().Get(context.Background(),
        &users.UserItemRequestBuilderGetRequestConfiguration{
            QueryParameters: &query,
        })
}

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

func greetUser(graphHelper *graphhelper.GraphHelper) {
    user, err := graphHelper.GetUser()
    if err != nil {
        log.Panicf("Error getting user: %v\n", err)
    }

    fmt.Printf("Hello, %s!\n", *user.GetDisplayName())

    // For Work/school accounts, email is in Mail property
    // Personal accounts, email is in UserPrincipalName
    email := user.GetMail()
    if email == nil {
        email = user.GetUserPrincipalName()
    }

    fmt.Printf("Email: %s\n", *email)
    fmt.Println()
}

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

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

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

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

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

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

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

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

Примечание.

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

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

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

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

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

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

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

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

Добавьте следующую функцию в ./graphhelper/graphhelper.go.

func (g *GraphHelper) GetInbox() (models.MessageCollectionResponseable, error) {
    var topValue int32 = 25
    query := users.ItemMailFoldersItemMessagesRequestBuilderGetQueryParameters{
        // Only request specific properties
        Select: []string{"from", "isRead", "receivedDateTime", "subject"},
        // Get at most 25 results
        Top: &topValue,
        // Sort by received time, newest first
        Orderby: []string{"receivedDateTime DESC"},
    }

    return g.userClient.Me().MailFolders().
        ByMailFolderId("inbox").
        Messages().
        Get(context.Background(),
            &users.ItemMailFoldersItemMessagesRequestBuilderGetRequestConfiguration{
                QueryParameters: &query,
            })
}

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

func listInbox(graphHelper *graphhelper.GraphHelper) {
    messages, err := graphHelper.GetInbox()
    if err != nil {
        log.Panicf("Error getting user's inbox: %v", err)
    }

    // Load local time zone
    // Dates returned by Graph are in UTC, use this
    // to convert to local
    location, err := time.LoadLocation("Local")
    if err != nil {
        log.Panicf("Error getting local timezone: %v", err)
    }

    // Output each message's details
    for _, message := range messages.GetValue() {
        fmt.Printf("Message: %s\n", *message.GetSubject())
        fmt.Printf("  From: %s\n", *message.GetFrom().GetEmailAddress().GetName())

        status := "Unknown"
        if *message.GetIsRead() {
            status = "Read"
        } else {
            status = "Unread"
        }
        fmt.Printf("  Status: %s\n", status)
        fmt.Printf("  Received: %s\n", (*message.GetReceivedDateTime()).In(location))
    }

    // If GetOdataNextLink does not return nil,
    // there are more messages available on the server
    nextLink := messages.GetOdataNextLink()

    fmt.Println()
    fmt.Printf("More messages available? %t\n", nextLink != nil)
    fmt.Println()
}

Запустите приложение, войдите в систему и выберите вариант 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: 2021-12-30 04:54:54 -0500 EST
Message: Employee Initiative Thoughts
  From: Patti Fernandez
  Status: Read
  Received: 2021-12-28 17:01:10 -0500 EST
Message: Voice Mail (11 seconds)
  From: Alex Wilber
  Status: Unread
  Received: 2021-12-28 17:00:46 -0500 EST
Message: Our Spring Blog Update
  From: Alex Wilber
  Status: Unread
  Received: 2021-12-28 16:49:46 -0500 EST
Message: Atlanta Flight Reservation
  From: Alex Wilber
  Status: Unread
  Received: 2021-12-28 16:35:42 -0500 EST
Message: Atlanta Trip Itinerary - down time
  From: Alex Wilber
  Status: Unread
  Received: 2021-12-28 16:22:04 -0500 EST

...

More messages available? True

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

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

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

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

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

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

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

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

Примечание.

Переданное значение Top является верхней границей, а не явным числом. API возвращает количество сообщений до указанного значения.

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

Если на сервере доступно больше результатов, ответы коллекции содержат @odata.nextLink свойство с URL-адресом API для доступа к следующей странице. Пакет SDK Для Go предоставляет этот метод в GetOdataNextLink качестве метода для объектов страницы коллекции. Если этот метод возвращает значение, отличное от nil, доступны дополнительные результаты.

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

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

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

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

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

Добавьте следующую функцию в ./graphhelper/graphhelper.go.

func (g *GraphHelper) SendMail(subject *string, body *string, recipient *string) error {
    // Create a new message
    message := models.NewMessage()
    message.SetSubject(subject)

    messageBody := models.NewItemBody()
    messageBody.SetContent(body)
    contentType := models.TEXT_BODYTYPE
    messageBody.SetContentType(&contentType)
    message.SetBody(messageBody)

    toRecipient := models.NewRecipient()
    emailAddress := models.NewEmailAddress()
    emailAddress.SetAddress(recipient)
    toRecipient.SetEmailAddress(emailAddress)
    message.SetToRecipients([]models.Recipientable{
        toRecipient,
    })

    sendMailBody := users.NewItemSendMailPostRequestBody()
    sendMailBody.SetMessage(message)

    // Send the message
    return g.userClient.Me().SendMail().Post(context.Background(), sendMailBody, nil)
}

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

func sendMail(graphHelper *graphhelper.GraphHelper) {
    // Send mail to the signed-in user
    // Get the user for their email address
    user, err := graphHelper.GetUser()
    if err != nil {
        log.Panicf("Error getting user: %v", err)
    }

    // For Work/school accounts, email is in Mail property
    // Personal accounts, email is in UserPrincipalName
    email := user.GetMail()
    if email == nil {
        email = user.GetUserPrincipalName()
    }

    subject := "Testing Microsoft Graph"
    body := "Hello world!"
    err = graphHelper.SendMail(&subject, &body, email)
    if err != nil {
        log.Panicf("Error sending mail: %v", err)
    }

    fmt.Println("Mail sent.")
    fmt.Println()
}

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

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

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

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

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

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

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

Добавьте следующую функцию в ./graphhelper/graphhelper.go.

func (g *GraphHelper) MakeGraphCall() error {
    // INSERT YOUR CODE HERE
    return nil
}

Замените пустую makeGraphCall функцию в graphtutorial.go следующим кодом.

func makeGraphCall(graphHelper *graphhelper.GraphHelper) {
    err := graphHelper.MakeGraphCall()
    if err != nil {
        log.Panicf("Error making Graph call: %v", err)
    }
}

Выбор API

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

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

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

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

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

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

Поделиться через

Создание приложений Go с помощью Microsoft Graph

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Выбор API

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

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

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