Бөлісу құралы:

Краткое руководство. Отправка сообщения электронной почты с помощью Службы коммуникации Azure

  • Мақала

Примечание.

Поделитесь своими мыслями и отзывами о Службы коммуникации Azure с нами, принимая этот короткий опрос.

В этом кратком руководстве описывается отправка электронной почты с помощью пакетов SDK для электронной почты.

Начало работы с Службы коммуникации Azure с помощью службы коммуникации попробуйте отправить сообщения электронной почты.

Необходимые компоненты

Выполнение этого краткого руководства предполагает небольшую дополнительную плату в несколько центов США в учетной записи Azure.

Отправка сообщения электронной почты с помощью пробной почты

Попробуйте использовать электронную почту, чтобы начать отправку сообщений электронной почты нужным получателям с помощью Службы коммуникации Azure, а также проверить конфигурацию приложения для отправки электронной почты. Это также помогает начать разработку уведомлений по электронной почте с помощью фрагмента кода в предпочтительном варианте языка.

Чтобы отправить сообщение получателю, а также указать тему и текст сообщения,

  1. На странице обзора подготовленного ресурса Службы коммуникации Azure щелкните " Попробовать электронную почту" на левой панели навигации в разделе "Электронная почта ".

    Снимок экрана: левая панель навигации для пробной почты.

  2. Выберите один из проверенных доменов в раскрывающемся списке.

    Снимок экрана, на котором показан защищенный домен из раскрывающегося списка.

  3. Создание сообщения электронной почты для отправки

    • Введите адрес электронной почты получателя
    • Ввод темы
    • Написание текста электронной почты

    Снимок экрана: фильтрация и выбор одного из проверенных доменов электронной почты для подключения.

  4. В нижней части страницы нажмите кнопку Отправить

    Снимок экрана: один из проверенных доменов электронной почты теперь подключен.

  5. Сообщение электронной почты успешно отправлено.

    Снимок экрана: успешная отправка электронной почты.

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

    • Выбор выбранного языка

    • Нажмите кнопку "Вставка подключения"

    • Нажмите кнопку "Копировать"

      Снимок экрана: фрагмент кода для отправки сообщения электронной почты.

  7. Фрагмент кода электронной почты теперь готов к использованию в проекте уведомлений.

Начало работы с Службы коммуникации Azure с помощью расширения коммуникации Azure CLI для отправки сообщений электронной почты.

Выполнение этого краткого руководства предполагает небольшую дополнительную плату в несколько центов США в учетной записи Azure.

Необходимые компоненты

Проверка предварительных условий

  • В окне терминала или командной строки выполните az --version команду, чтобы проверить, установлен ли Azure CLI и расширение связи.
  • Чтобы просмотреть домены, проверенные ресурсом Служб коммуникации электронной почты, войдите в портал Azure. Найдите ресурс Служб коммуникации электронной почты и откройте вкладку "Подготовка доменов " в области навигации слева.

Установка

Добавление расширения

Добавьте расширение Службы коммуникации Azure для Azure CLI с помощью az extension команды.

az extension add --name communication

Вход в Azure CLI

Вам нужно войти в Azure CLI. Вы можете выполнить команду из az login терминала и предоставить учетные данные.

Сохранение строки подключения в переменной среды

Вы можете настроить AZURE_COMMUNICATION_CONNECTION_STRING переменную среды для использования операций ключей Azure CLI без необходимости --connection_string передавать строка подключения. Чтобы настроить переменную среды, откройте окно консоли и выберите операционную систему на следующих вкладках. Замените <connectionString> фактической строкой подключения.

Примечание.

Не сохраняйте строка подключения как незашифрованную переменную среды для рабочих сред. Это предназначено только для тестирования. Для рабочих сред следует создать новые строка подключения. Мы рекомендуем регулярно шифровать строка подключения и изменять их.

setx AZURE_COMMUNICATION_CONNECTION_STRING "<yourConnectionString>"

После добавления переменной среды может потребоваться перезапустить все запущенные приложения, которым может понадобиться считать переменную среды, в том числе окно консоли. Например, если вы используете Visual Studio в качестве редактора, перезапустите Visual Studio перед запуском примера.

Отправляет сообщение электронной почты.

az communication email send
	--connection-string "yourConnectionString"
	--sender "<donotreply@xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx.azurecomm.net>"
	--to "<emailalias@emaildomain.com>"
	--subject "Welcome to Azure Communication Services Email" --text "This email message is sent from Azure Communication Services Email using Azure CLI."

Выполните следующие замены в коде:

  • Замените <yourConnectionString> строка подключения.
  • Замените <emailalias@emaildomain.com> адрес электронной почты, на который вы хотите отправить сообщение.
  • Замените <donotreply@xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx.azurecomm.net> адрес MailFrom проверенного домена.

Приведенная выше команда также выполняет опрос по идентификатору messageId и возвращает состояние доставки электронной почты. Состояние может принимать следующие значения.

Название статуса Description
NotStarted В настоящее время мы не отправляем это состояние из нашей службы.
Выполняется Операция отправки электронной почты в настоящее время выполняется и обрабатывается.
Выполнено Операция отправки электронной почты завершена без ошибок, и сообщение электронной почты выходит за доставку. Любое подробное состояние доставки электронной почты за пределами этого этапа можно получить через Azure Monitor или через Сетка событий Azure. Узнайте, как подписаться на события электронной почты
Неудачно Операция отправки электронной почты не прошла успешно и возникла ошибка. Сообщение не было отправлено. Результат содержит объект ошибки с дополнительными сведениями о причине сбоя.

Необязательные параметры

Следующие необязательные параметры доступны в Azure CLI.

  • --html можно использовать вместо --text html-текста электронной почты.

  • --importance задает тип важности для сообщения электронной почты. Известные значения: высокий, нормальный и низкий. По умолчанию используется нормально.

  • --to задает список получателей электронной почты.

  • --cc задает адреса электронной почты для углеродного копирования.

  • --bcc задает слепые адреса электронной почты для копирования углерода.

  • --reply-to задает адрес электронной почты для ответа на сообщение.

  • --disable-tracking указывает, следует ли отключать отслеживание взаимодействия пользователей для этого запроса.

  • --attachments задает список вложений электронной почты.

  • --attachment-types задает список типов вложений электронной почты в том же порядке вложений.

Кроме того, можно использовать список получателей и --cc --bcc аналогичный --to. Должен быть по крайней мере один получатель --to или --cc --bcc.

Начало работы со Службами коммуникации Azure с помощью клиентской библиотеки электронной почты Служб коммуникации Azure для C# для отправки сообщений электронной почты.

Совет

Переход к интерфейсу отправки электронной почты с Службы коммуникации Azure путем пропуска непосредственно к базовой отправке электронной почты и расширенной отправке электронной почты на GitHub.

Общие сведения об объектной модели электронной почты

Следующие классы и интерфейсы реализуют некоторые основные функции клиентской библиотеки Служб коммуникации электронной почты для C#.

Имя Описание
EmailAddress Этот класс содержит адрес электронной почты и параметр отображаемого имени.
EmailAttachment Этот класс создает вложение электронной почты, принимая уникальный идентификатор, строку типа MIME вложения электронной почты, двоичные данные для содержимого и необязательный идентификатор содержимого, чтобы определить его как встроенное вложение.
EmailClient Этот класс требуется для реализации всех функций электронной почты. Вы создаете его с помощью строки подключения и используете для отправки сообщений электронной почты.
EmailClientOptions Этот класс можно добавить в экземпляр EmailClient для конкретной версии API.
EmailContent Этот класс содержит тему и текст сообщения электронной почты. Необходимо указать по крайней мере одно из содержимого PlainText или Html
EmailCustomHeader Этот класс позволяет добавить пару имени и значения для настраиваемого заголовка. Важность электронной почты также можно указать с помощью этих заголовков с помощью имени заголовка x-priority или x-msmail-priority.
EmailMessage Этот класс объединяет отправителя, содержимое и получателей. Также можно добавить пользовательские заголовки, вложения и адреса электронной почты с ответом.
EmailRecipients Этот класс содержит списки объектов EmailAddress для получателей сообщения электронной почты, включая необязательные списки для получателей CC и BCC.
EmailSendOperation Этот класс представляет асинхронную операцию отправки электронной почты и возвращается из вызова API отправки электронной почты.
EmailSendResult Этот класс содержит результаты операции отправки электронной почты. Он имеет идентификатор операции, состояние операции и объект ошибки (если применимо).

EmailSendResult возвращает следующее состояние операции электронной почты.

Состояние Description
NotStarted В настоящее время мы не отправляем это состояние из нашей службы.
Выполняется Операция отправки электронной почты в настоящее время выполняется и обрабатывается.
Выполнено Операция отправки электронной почты завершена без ошибок, и сообщение электронной почты выходит за доставку. Любое подробное состояние доставки электронной почты за пределами этого этапа можно получить через Azure Monitor или через Сетка событий Azure. Узнайте, как подписаться на события электронной почты
Неудачно Операция отправки электронной почты не прошла успешно и возникла ошибка. Сообщение не было отправлено. Результат содержит объект ошибки с дополнительными сведениями о причине сбоя.

Необходимые компоненты

Выполнение этого краткого руководства предполагает небольшую дополнительную плату в несколько центов США в учетной записи Azure.

Примечание.

Мы также можем отправить сообщение электронной почты из собственного проверенного домена. Добавьте настраиваемые проверенные домены в службу коммуникации электронной почты.

Проверка предварительных условий

  • В окне терминала или команды выполните команду dotnet, чтобы проверить, установлена ли клиентская библиотека .NET.
  • Чтобы посмотреть поддомены, связанные с ресурсом Служб коммуникации, войдите на портал Azure, перейдите к ресурсу коммуникации электронной почты и откройте вкладку Подготовка доменов в области навигации слева.

Создание нового приложения C#

В окне консоли (cmd, PowerShell или Bash) выполните команду dotnet new, чтобы создать консольное приложение с именем EmailQuickstart. Эта команда создает простой проект "Hello World" на языке C# с одним файлом исходного кода Program.cs.

dotnet new console -o EmailQuickstart

Измените каталог на только что созданную папку приложения и выполните команду dotnet build, чтобы скомпилировать приложение.

cd EmailQuickstart
dotnet build

Установка пакета

Оставаясь в каталоге приложения, установите пакет клиентской библиотеки Коммуникации электронной почты для .NET с помощью команды dotnet add package.

dotnet add package Azure.Communication.Email

Создание клиента электронной почты с проверкой подлинности

Откройте файл Program.cs и замените существующий код следующим кодом, чтобы добавить using директивы для включения Azure.Communication.Email пространства имен и отправной точки для выполнения программы.

using System;
using System.Collections.Generic;
using System.Threading;
using System.Threading.Tasks;

using Azure;
using Azure.Communication.Email;

namespace SendEmail
{
  internal class Program
  {
    static async Task Main(string[] args)
    {

    }
  }
}

Существует несколько различных вариантов проверки подлинности клиента электронной почты:

Откройте Program.cs в текстовом редакторе и замените текст метода Main кодом, чтобы инициализировать EmailClient с помощью строки подключения. Следующий код извлекает строка подключения ресурса из переменной среды с именемCOMMUNICATION_SERVICES_CONNECTION_STRING. См. сведения о том, как управлять строкой подключения ресурса.

// This code demonstrates how to fetch your connection string
// from an environment variable.
string connectionString = Environment.GetEnvironmentVariable("COMMUNICATION_SERVICES_CONNECTION_STRING");
EmailClient emailClient = new EmailClient(connectionString);

Примечание.

Рекомендуется использовать опрос вручную (отправить электронную почту с асинхронным опросом состояния) для отправки электронной почты.

Базовая отправка электронной почты

Создание сообщения электронной почты

Чтобы отправить сообщение электронной почты, необходимо:

  • Определите тему и текст электронной почты.
  • Определите Адрес отправителя. Создайте сообщение электронной почты с информацией отправителя, с которой вы получаете адрес MailFrom из проверенного домена.
  • Определите адрес получателя.
  • Вызовите метод SendAsync. Добавьте следующий код в конец метода Main в Program.cs:

Замените сведения о домене своими и измените содержимое, сведения о получателе по мере необходимости


//Replace with your domain and modify the content, recipient details as required

var subject = "Welcome to Azure Communication Service Email APIs.";
var htmlContent = "<html><body><h1>Quick send email test</h1><br/><h4>This email message is sent from Azure Communication Service Email.</h4><p>This mail was sent using .NET SDK!!</p></body></html>";
var sender = "donotreply@xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx.azurecomm.net";
var recipient = "emailalias@contoso.com";

Отправка и получение состояния отправки электронной почты

При вызове SendAsync с помощью Azure.WaitUntil.Started метод возвращается обратно после запуска операции. Метод возвращает объект EmailSendOperation. Чтобы обновить состояние операции электронной почты, можно вызвать метод UpdateStatusAsync.

Возвращенный объект EmailSendOperation содержит объект EmailSendStatus, содержащий:

  • Текущее состояние операции отправки электронной почты.
  • Объект ошибки с сведениями о сбое, если текущее состояние находится в состоянии сбоя.

/// Send the email message with WaitUntil.Started
EmailSendOperation emailSendOperation = await emailClient.SendAsync(
    Azure.WaitUntil.Started,
    sender,
    recipient,
    subject,
    htmlContent);

/// Call UpdateStatus on the email send operation to poll for the status
/// manually.
try
{
    while (true)
    {
        await emailSendOperation.UpdateStatusAsync();
        if (emailSendOperation.HasCompleted)
        {
            break;
        }
        await Task.Delay(100);
    }

    if (emailSendOperation.HasValue)
    {
        Console.WriteLine($"Email queued for delivery. Status = {emailSendOperation.Value.Status}");
    }
}
catch (RequestFailedException ex)
{
    Console.WriteLine($"Email send failed with Code = {ex.ErrorCode} and Message = {ex.Message}");
}

/// Get the OperationId so that it can be used for tracking the message for troubleshooting
string operationId = emailSendOperation.Id;
Console.WriteLine($"Email operation id = {operationId}");

Запустите приложение из каталога приложения с помощью команды dotnet run.

dotnet run

Пример кода

Пример приложения можно скачать в репозитории GitHub.

Начало работы со Службами коммуникации Azure с помощью клиентской библиотеки электронной почты Служб коммуникации Azure для JS для отправки сообщений электронной почты.

Совет

Переход к интерфейсу отправки электронной почты с Службы коммуникации Azure путем пропуска непосредственно к базовой отправке электронной почты и расширенной отправке электронной почты на GitHub.

Общие сведения об объектной модели электронной почты

Следующие классы и интерфейсы реализуют некоторые основные функции клиентской библиотеки чата Служб коммуникации электронной почты для JavaScript.

Имя Описание
EmailAddress Этот класс содержит адрес электронной почты и параметр отображаемого имени.
EmailAttachment Этот класс создает вложение электронной почты, принимая уникальный идентификатор, строку типа MIME вложения электронной почты, двоичные данные для содержимого и необязательный идентификатор содержимого, чтобы определить его как встроенное вложение.
EmailClient Этот класс требуется для реализации всех функций электронной почты. Вы создаете его с помощью строки подключения и используете для отправки сообщений электронной почты.
EmailClientOptions Этот класс можно добавить в экземпляр EmailClient для конкретной версии API.
EmailContent Этот класс содержит тему и текст сообщения электронной почты. Необходимо указать по крайней мере одно из содержимого PlainText или Html.
EmailCustomHeader Этот класс позволяет добавить пару имени и значения для настраиваемого заголовка. Важность электронной почты также можно указать с помощью этих заголовков с помощью имени заголовка x-priority или x-msmail-priority.
EmailMessage Этот класс объединяет отправителя, содержимое и получателей. Также можно добавить пользовательские заголовки, вложения и адреса электронной почты с ответом.
EmailRecipients Этот класс содержит списки объектов EmailAddress для получателей сообщения электронной почты, включая необязательные списки для получателей CC и BCC.
EmailSendResult Этот класс содержит результаты операции отправки электронной почты. Он имеет идентификатор операции, состояние операции и объект ошибки (если применимо).
EmailSendStatus Этот класс представляет набор состояний операции отправки электронной почты.

EmailSendResult возвращает следующее состояние операции электронной почты.

Название статуса Description
isStarted Возвращает значение true, если операция отправки электронной почты в настоящее время выполняется и обрабатывается.
IsCompleted Возвращает значение true, если операция отправки электронной почты завершена без ошибок, и сообщение электронной почты выходит за доставку. Любое подробное состояние доставки электронной почты за пределами этого этапа можно получить через Azure Monitor или через Сетка событий Azure. Узнайте, как подписаться на события электронной почты
result Свойство, которое существует, если операция отправки электронной почты завершилась.
error Свойство, которое существует, если операция отправки электронной почты не была успешной и возникла ошибка. Сообщение не было отправлено. Результат содержит объект ошибки с дополнительными сведениями о причине сбоя.

Необходимые компоненты

Выполнение этого краткого руководства предполагает небольшую дополнительную плату в несколько центов США в учетной записи Azure.

Примечание.

Мы также можем отправить сообщение электронной почты из собственного проверенного домена. Добавьте настраиваемые проверенные домены в службу коммуникации электронной почты.

Проверка предварительных условий

  • В терминале или командном окне воспользуйтесь node --version, чтобы проверить, установлен ли пакет Node.js.
  • Чтобы посмотреть домены, проверенные ресурсом Служб коммуникации, войдите на портал Azure, перейдите к ресурсу коммуникации электронной почты и откройте вкладку Подготовка доменов в области навигации слева.

Настройка среды приложения

Создание нового приложения Node.js

Откройте терминал или командное окно, создайте каталог для своего приложения и перейдите к нему.

mkdir email-quickstart && cd email-quickstart

Воспользуйтесь командой npm init -y, чтобы создать файл package.json с параметрами по умолчанию.

npm init -y

Используйте текстовый редактор, чтобы создать файл с именем send-sms.js в корневом каталоге проекта. Измените свойство main в файле package.json на send-email.js. В следующем разделе показано, как добавить исходный код для этого краткого руководства в созданный файл.

Установка пакета

Используйте команду npm install, чтобы установить клиентскую библиотеку Служб коммуникации электронной почты для JavaScript.

npm install @azure/communication-email --save

Параметр --save указывает библиотеку как зависимость в файле пакета package.json.

Создание клиента электронной почты с проверкой подлинности

Существует несколько различных вариантов проверки подлинности клиента электронной почты:

Импортируйте EmailClient из клиентской библиотеки и создайте его экземпляр с помощью строки подключения.

Следующий код извлекает строка подключения ресурса из переменной среды с именем COMMUNICATION_SERVICES_CONNECTION_STRING пакета dotenv. С помощью команды npm install установите пакет dotenv. См. сведения о том, как управлять строкой подключения ресурса.

npm install dotenv

Добавьте в send-sms.js следующий код:

const { EmailClient } = require("@azure/communication-email");
require("dotenv").config();

// This code demonstrates how to fetch your connection string
// from an environment variable.
const connectionString = process.env['COMMUNICATION_SERVICES_CONNECTION_STRING'];
const emailClient = new EmailClient(connectionString);

Для простоты в этом кратком руководстве используются строка подключения, но в рабочих средах рекомендуется использовать субъекты-службы.

Базовая отправка электронной почты

Отправляет сообщение электронной почты.

Чтобы отправить сообщение электронной почты, вызовите beginSend функцию из EmailClient. Этот метод возвращает опрашиватель, который проверяет состояние операции и извлекает результат после завершения.


async function main() {
  const POLLER_WAIT_TIME = 10
  try {
    const message = {
      senderAddress: "<donotreply@xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx.azurecomm.net>",
      content: {
        subject: "Welcome to Azure Communication Services Email",
        plainText: "This email message is sent from Azure Communication Services Email using the JavaScript SDK.",
      },
      recipients: {
        to: [
          {
            address: "<emailalias@emaildomain.com>",
            displayName: "Customer Name",
          },
        ],
      },
    };

    const poller = await emailClient.beginSend(message);

    if (!poller.getOperationState().isStarted) {
      throw "Poller was not started."
    }

    let timeElapsed = 0;
    while(!poller.isDone()) {
      poller.poll();
      console.log("Email send polling in progress");

      await new Promise(resolve => setTimeout(resolve, POLLER_WAIT_TIME * 1000));
      timeElapsed += 10;

      if(timeElapsed > 18 * POLLER_WAIT_TIME) {
        throw "Polling timed out.";
      }
    }

    if(poller.getResult().status === KnownEmailSendStatus.Succeeded) {
      console.log(`Successfully sent the email (operation id: ${poller.getResult().id})`);
    }
    else {
      throw poller.getResult().error;
    }
  } catch (e) {
    console.log(e);
  }
}

main();

Выполните следующие замены в коде:

  • Замените <emailalias@emaildomain.com> адрес электронной почты, на который вы хотите отправить сообщение.
  • Замените <donotreply@xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx.azurecomm.net> адрес MailFrom проверенного домена.

Выполнение кода

Используйте команду node для выполнения кода, добавленного в файл send-email.js.

node ./send-email.js

Пример кода

Пример приложения можно скачать в репозитории GitHub.

Приступая к работе с Службы коммуникации Azure с помощью пакета SDK для электронной почты java для служб коммуникации для отправки сообщений электронной почты.

Совет

Переход к интерфейсу отправки электронной почты с Службы коммуникации Azure путем пропуска непосредственно к базовой отправке электронной почты и расширенной отправке электронной почты на GitHub.

Общие сведения об объектной модели электронной почты

Следующие классы и интерфейсы обрабатывают некоторые основные функции пакета SDK для электронной почты Службы коммуникации Azure для Python.

Имя Описание
EmailAddress Этот класс содержит адрес электронной почты и параметр отображаемого имени.
EmailAttachment Этот интерфейс создает вложение электронной почты, принимая уникальный идентификатор, строку типа MIME вложения электронной почты, строку байтов содержимого и необязательный идентификатор содержимого, чтобы определить его как встроенное вложение.
EmailClient Этот класс требуется для реализации всех функций электронной почты. Вы создаете его с помощью строки подключения и используете для отправки сообщений электронной почты.
EmailMessage Этот класс объединяет отправителя, содержимое и получателей. Также можно добавить пользовательские заголовки, вложения и адреса электронной почты с ответом.
EmailSendResult Этот класс содержит результаты операции отправки электронной почты. Он имеет идентификатор операции, состояние операции и объект ошибки (если применимо).
EmailSendStatus Этот класс представляет набор состояний операции отправки электронной почты.

EmailSendResult возвращает следующее состояние операции электронной почты.

Название статуса Description
NOT_STARTED В настоящее время мы не отправляем это состояние из нашей службы.
IN_PROGRESS Операция отправки электронной почты в настоящее время выполняется и обрабатывается.
SUCCESSFULLY_COMPLETED Операция отправки электронной почты завершена без ошибок, и сообщение электронной почты выходит за доставку. Любое подробное состояние доставки электронной почты за пределами этого этапа можно получить через Azure Monitor или через Сетка событий Azure. Узнайте, как подписаться на события электронной почты
СБОЙ Операция отправки электронной почты не прошла успешно и возникла ошибка. Сообщение не было отправлено. Результат содержит объект ошибки с дополнительными сведениями о причине сбоя.

Необходимые компоненты

Выполнение этого краткого руководства предполагает небольшую дополнительную плату в несколько центов США в учетной записи Azure.

Примечание.

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

Проверка предварительных условий

  • В окне терминала или командной строки выполните команду mvn -v , чтобы проверить, установлен ли Maven.
  • Чтобы просмотреть домены, проверенные ресурсом Служб коммуникации электронной почты, войдите в портал Azure. Найдите ресурс Служб коммуникации электронной почты и откройте вкладку "Подготовка доменов " в области навигации слева.

Настройка среды приложения

Чтобы настроить среду для отправки сообщений электронной почты, выполните действия, описанные в следующих разделах.

Создание нового приложения Java

Откройте терминал или командное окно и перейдите в каталог, в котором необходимо создать приложение Java. Выполните следующую команду, чтобы создать проект Java из шаблона maven-archetype-quickstart.

mvn archetype:generate -DarchetypeArtifactId="maven-archetype-quickstart" -DarchetypeGroupId="org.apache.maven.archetypes" -DarchetypeVersion="1.4" -DgroupId="com.communication.quickstart" -DartifactId="communication-quickstart"

Цель generate создает каталог с тем же именем, что artifactId и значение. В этом каталоге каталог src/main/java содержит исходный код проекта, каталог src/test/java содержит источник теста, а файл pom.xml — объектную модель проекта проекта (POM).

Установка пакета

Откройте файл pom.xml в текстовом редакторе. Добавьте приведенный ниже элемент зависимости в группу зависимостей.

<dependency>
    <groupId>com.azure</groupId>
    <artifactId>azure-communication-email</artifactId>
    <version>1.0.0-beta.2</version>
</dependency>

Настройка платформы приложения

Откройте /src/main/java/com/communication/quickstart/App.java в текстовом редакторе, добавьте директивы импорта и удалите инструкцию System.out.println("Hello world!"); :

package com.communication.quickstart;

import com.azure.communication.email.models.*;
import com.azure.communication.email.*;
import com.azure.core.util.polling.*;

public class App
{
    public static void main( String[] args )
    {
        // Quickstart code goes here.
    }
}

Создание клиента электронной почты с проверкой подлинности

Существует несколько различных вариантов проверки подлинности клиента электронной почты.

Чтобы выполнить проверку подлинности клиента, создайте экземпляр EmailClient строка подключения. См. сведения о том, как управлять строкой подключения ресурса. Вы также можете инициализировать клиент с помощью любого пользовательского HTTP-клиента, реализующего com.azure.core.http.HttpClient интерфейс.

Чтобы создать экземпляр синхронного клиента, добавьте следующий код в main метод:

// You can get your connection string from your resource in the Azure portal.
String connectionString = "endpoint=https://<resource-name>.communication.azure.com/;accesskey=<access-key>";

EmailClient emailClient = new EmailClientBuilder()
    .connectionString(connectionString)
    .buildClient();

Чтобы создать экземпляр асинхронного клиента, добавьте следующий код в main метод:

// You can get your connection string from your resource in the Azure portal.
String connectionString = "endpoint=https://<resource-name>.communication.azure.com/;accesskey=<access-key>";

EmailAsyncClient emailClient = new EmailClientBuilder()
    .connectionString(connectionString)
    .buildAsyncClient();

Для простоты в этом кратком руководстве используются строка подключения, но в рабочих средах рекомендуется использовать субъекты-службы.

Базовая отправка электронной почты

Сообщение электронной почты можно создать с помощью EmailMessage объекта в пакете SDK.

EmailMessage message = new EmailMessage()
    .setSenderAddress("<donotreply@xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx.azurecomm.net>")
    .setToRecipients("<emailalias@emaildomain.com>")
    .setSubject("Welcome to Azure Communication Services Email")
    .setBodyPlainText("This email message is sent from Azure Communication Services Email using the Java SDK.");

Выполните следующие замены в коде:

  • Замените <emailalias@emaildomain.com> адрес электронной почты, на который вы хотите отправить сообщение.
  • Замените <donotreply@xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx.azurecomm.net> адрес MailFrom проверенного домена.

Чтобы отправить сообщение электронной почты, вызовите beginSend функцию из EmailClient.

Вызов beginSend клиента синхронизации возвращает SyncPoller объект, который можно использовать для проверки состояния операции и получения результата после завершения. Обратите внимание, что первоначальный запрос на отправку сообщения электронной почты будет отправлен сразу после beginSend вызова метода. Отправка сообщения электронной почты является длительной операцией. Важно отметить, что getFinalResult() метод в опросе является блокирующей операцией до достижения состояния терминала (SUCCESSFULLY_COMPLETED или FAILED) . Рекомендуемый метод — выполнять опрос вручную через интервал, соответствующий потребностям приложения, как показано в примере ниже.

try
{
    SyncPoller<EmailSendResult, EmailSendResult> poller = emailClient.beginSend(message, null); // This will send out the initial request to send an email

    PollResponse<EmailSendResult> pollResponse = null;

    Duration timeElapsed = Duration.ofSeconds(0);
    Duration POLLER_WAIT_TIME = Duration.ofSeconds(10);

    // Polling is done manually to avoid blocking the application in case of an error
    while (pollResponse == null
            || pollResponse.getStatus() == LongRunningOperationStatus.NOT_STARTED
            || pollResponse.getStatus() == LongRunningOperationStatus.IN_PROGRESS)
    {
        pollResponse = poller.poll();
        System.out.println("Email send poller status: " + pollResponse.getStatus());

        Thread.sleep(POLLER_WAIT_TIME.toMillis());
        timeElapsed = timeElapsed.plus(POLLER_WAIT_TIME);

        if (timeElapsed.compareTo(POLLER_WAIT_TIME.multipliedBy(18)) >= 0)
        {
            throw new RuntimeException("Polling timed out.");
        }
    }

    if (poller.getFinalResult().getStatus() == EmailSendStatus.SUCCEEDED)
    {
        System.out.printf("Successfully sent the email (operation id: %s)", poller.getFinalResult().getId());
    }
    else
    {
        throw new RuntimeException(poller.getFinalResult().getError().getMessage());
    }
}
catch (Exception exception)
{
    System.out.println(exception.getMessage());
}

Выполнение кода

  1. Перейдите в каталог, содержащий файл pom.xml и скомпилируйте проект с помощью mvn команды.

    mvn compile

  2. Создайте пакет.

    mvn package

  3. Выполните следующую команду mvn для запуска приложения.

    mvn exec:java -D"exec.mainClass"="com.communication.quickstart.App" -D"exec.cleanupDaemonThreads"="false"

Пример кода

Пример приложения можно скачать в репозитории GitHub.

Начало работы с Службы коммуникации Azure с помощью пакета SDK для электронной почты Python для служб коммуникации для отправки сообщений электронной почты.

Совет

Переход к интерфейсу отправки электронной почты с Службы коммуникации Azure путем пропуска непосредственно к базовой отправке электронной почты и расширенной отправке электронной почты на GitHub.

Общие сведения об объектной модели электронной почты

В следующем шаблоне сообщения JSON и объекте ответа демонстрируются некоторые основные функции пакета SDK для электронной почты Службы коммуникации Azure для Python.

message = {
    "content": {
        "subject": "str",  # Subject of the email message. Required.
        "html": "str",  # Optional. Html version of the email message.
        "plainText": "str"  # Optional. Plain text version of the email
            message.
    },
    "recipients": {
        "to": [
            {
                "address": "str",  # Email address. Required.
                "displayName": "str"  # Optional. Email display name.
            }
        ],
        "bcc": [
            {
                "address": "str",  # Email address. Required.
                "displayName": "str"  # Optional. Email display name.
            }
        ],
        "cc": [
            {
                "address": "str",  # Email address. Required.
                "displayName": "str"  # Optional. Email display name.
            }
        ]
    },
    "senderAddress": "str",  # Sender email address from a verified domain. Required.
    "attachments": [
        {
            "contentInBase64": "str",  # Base64 encoded contents of the attachment. Required.
            "contentType": "str",  # MIME type of the content being attached. Required.
            "name": "str"  # Name of the attachment. Required.
        }
    ],
    "userEngagementTrackingDisabled": bool,  # Optional. Indicates whether user engagement tracking should be disabled for this request if the resource-level user engagement tracking setting was already enabled in the control plane.
    "headers": {
        "str": "str"  # Optional. Custom email headers to be passed.
    },
    "replyTo": [
        {
            "address": "str",  # Email address. Required.
            "displayName": "str"  # Optional. Email display name.
        }
    ]
}

response = {
    "id": "str",  # The unique id of the operation. Uses a UUID. Required.
    "status": "str",  # Status of operation. Required. Known values are:
        "NotStarted", "Running", "Succeeded", and "Failed".
    "error": {
        "additionalInfo": [
            {
                "info": {},  # Optional. The additional info.
                "type": "str"  # Optional. The additional info type.
            }
        ],
        "code": "str",  # Optional. The error code.
        "details": [
            ...
        ],
        "message": "str",  # Optional. The error message.
        "target": "str"  # Optional. The error target.
    }
}

Значения response.status описаны далее в следующей таблице.

Название статуса Description
InProgress Операция отправки электронной почты в настоящее время выполняется и обрабатывается.
Выполнено Операция отправки электронной почты завершена без ошибок, и сообщение электронной почты выходит за доставку. Любое подробное состояние доставки электронной почты за пределами этого этапа можно получить через Azure Monitor или через Сетка событий Azure. Узнайте, как подписаться на события электронной почты
Неудачно Операция отправки электронной почты не прошла успешно и возникла ошибка. Сообщение не было отправлено. Результат содержит объект ошибки с дополнительными сведениями о причине сбоя.

Необходимые компоненты

Выполнение этого краткого руководства предполагает небольшую дополнительную плату в несколько центов США в учетной записи Azure.

Примечание.

Мы также можем отправить сообщение электронной почты из собственного проверенного домена. Добавьте настраиваемые проверенные домены в службу коммуникации электронной почты.

Проверка предварительных условий

  • В окне терминала или команды выполните команду python --version, чтобы проверить, установлен ли пакет Python.
  • Чтобы просмотреть домены, проверенные ресурсом Служб коммуникации электронной почты, войдите в портал Azure. Найдите ресурс Служб коммуникации электронной почты и откройте вкладку "Подготовка доменов " в области навигации слева.

Настройка среды приложения

Чтобы настроить среду для отправки сообщений электронной почты, выполните действия, описанные в следующих разделах.

Создание приложения Python

  1. Откройте терминал или командное окно. Затем выполните следующую команду, чтобы создать виртуальную среду и активировать ее. Эта команда создает новый каталог для приложения.

    python -m venv email-quickstart

  2. Перейдите в корневой каталог виртуальной среды и активируйте его с помощью следующих команд.

    cd email-quickstart
.\Scripts\activate

  3. Используйте текстовый редактор, чтобы создать файл с именем send-email.py в корневом каталоге проекта и добавить структуру для программы, включая базовую обработку исключений.

    import os
from azure.communication.email import EmailClient

try:
    # Quickstart code goes here.
except Exception as ex:
    print('Exception:')
    print(ex)

В следующих разделах вы добавите весь исходный код для этого краткого руководства в созданный файл send-email.py .

Установка пакета

В каталоге приложений установите пакет SDK для электронной почты Службы коммуникации Azure для Python с помощью следующей команды.

pip install azure-communication-email

Создание клиента электронной почты с проверкой подлинности

Существует несколько различных вариантов проверки подлинности клиента электронной почты:

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

# Create the EmailClient object that you use to send Email messages.
email_client = EmailClient.from_connection_string(<connection_string>)

Для простоты в этом кратком руководстве используются строка подключения, но в рабочих средах рекомендуется использовать субъекты-службы.

Базовая отправка электронной почты

Отправляет сообщение электронной почты.

Чтобы отправить сообщение электронной почты, необходимо:

  • Создайте сообщение со следующими значениями:
    • senderAddress: допустимый адрес электронной почты отправителя, найденный в поле MailFrom в области обзора домена, связанного с ресурсом служб коммуникации электронной почты.
    • recipients: объект со списком получателей электронной почты, а также списки получателей электронной почты CC и BCC.
    • content: объект, содержащий тему, и при необходимости обычный текст или HTML-содержимое сообщения электронной почты.
  • Вызовите метод begin_send, который возвращает результат операции.
message = {
    "content": {
        "subject": "This is the subject",
        "plainText": "This is the body",
        "html": "<html><h1>This is the body</h1></html>"
    },
    "recipients": {
        "to": [
            {
                "address": "<emailalias@emaildomain.com>",
                "displayName": "Customer Name"
            }
        ]
    },
    "senderAddress": "<donotreply@xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx.azurecomm.net>"
}

poller = email_client.begin_send(message)
print("Result: " + poller.result())

Выполните следующие замены в коде:

  • Замените <emailalias@emaildomain.com> адрес электронной почты, на который вы хотите отправить сообщение.
  • Замените <donotreply@xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx.azurecomm.net> адрес MailFrom проверенного домена.

Получение состояния доставки электронной почты

Мы можем пропросить состояние доставки электронной почты, задав цикл объекта состояния операции, возвращаемого методом EmailClient begin_send :

POLLER_WAIT_TIME = 10

try:
    email_client = EmailClient.from_connection_string(connection_string)

    poller = email_client.begin_send(message);

    time_elapsed = 0
    while not poller.done():
        print("Email send poller status: " + poller.status())

        poller.wait(POLLER_WAIT_TIME)
        time_elapsed += POLLER_WAIT_TIME

        if time_elapsed > 18 * POLLER_WAIT_TIME:
            raise RuntimeError("Polling timed out.")

    if poller.result()["status"] == "Succeeded":
        print(f"Successfully sent the email (operation id: {poller.result()['id']})")
    else:
        raise RuntimeError(str(poller.result()["error"]))

except Exception as ex:
    print(ex)

Выполнение кода

Запустите приложение из каталога приложения с помощью команды python.

python send-email.py

Пример кода

Пример приложения можно скачать в репозитории GitHub.

Необходимые компоненты

  • Учетная запись Azure с активной подпиской. Создать бесплатную учетную запись Azure.

  • Активный ресурс Служб коммуникации Azure. Создать ресурс Служб коммуникации.

  • Активный ресурс Azure Logic Apps (приложение логики) и рабочий процесс или создайте новый ресурс приложения логики и рабочий процесс с триггером, который требуется использовать. В настоящее время соединитель электронной почты Службы коммуникации Azure предоставляет только действия, поэтому рабочий процесс приложения логики требует триггера, как минимум. Вы можете создать ресурс приложения логики "Потребление" или "Стандартный".

  • Ресурс электронной почты Службы коммуникации Azure с настроенным доменом или личным доменом.

  • Ресурс Службы коммуникации Azure, подключенный к домену электронной почты Azure.

Отправить сообщение эл. почты

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

  1. В конструкторе откройте рабочий процесс приложения логики.

    Потребление

    1. На шаге, в котором нужно добавить новое действие, выберите новый шаг. Кроме того, чтобы добавить новое действие между шагами, переместите указатель на стрелку между этими шагами, выберите знак плюса (+) и нажмите кнопку "Добавить действие".

    2. В поле "Выбор операции" выберите "Премиум". В поле поиска введите сообщение электронной почты Azure Communication Email.

    3. В списке действий выберите "Отправить сообщение электронной почты".

      Снимок экрана: действие отправки электронной почты Службы коммуникации Azure соединителя электронной почты.

    Стандартные

    1. На шаге, в котором нужно добавить новое действие, выберите знак плюса (+). Кроме того, чтобы добавить новое действие между шагами, переместите указатель на стрелку между этими шагами, выберите знак плюса (+) и нажмите кнопку "Добавить действие".

    2. В раскрывающемся списке "Добавить действие " выберите "Премиум " в раскрывающемся списке среды выполнения. В поле поиска введите сообщение электронной почты Azure Communication Email.

    3. В списке действий выберите "Отправить сообщение электронной почты".

  2. Укажите имя подключения.

  3. Введите строка подключения для ресурса Службы коммуникации Azure. Чтобы найти эту строку, выполните следующие действия.

    1. В портал Azure откройте ресурс Службы коммуникации Azure.

    2. В меню ресурсов в разделе "Параметры" выберите "Ключи" и скопируйте строка подключения.

      Снимок экрана: строка подключения Службы коммуникации Azure.

  4. По завершении нажмите Создать.

  5. В поле From используйте адрес электронной почты, настроенный в предварительных требованиях. Введите значения полей "Электронная почта", "Тема" и "Текст ", например:

    Снимок экрана: входные данные действия отправки действия электронной почты Службы коммуникации Azure соединителя электронной почты.

  6. Сохраните результаты своих действий. На панели инструментов конструктора выберите Сохранить.

Тестирование рабочего процесса

На основе наличия рабочего процесса "Потребление" или "Стандартный" вручную запустите рабочий процесс:

  • Потребление: на панели инструментов конструктора нажмите кнопку "Запустить триггер>".
  • Стандартный: в меню рабочего процесса выберите "Обзор". На панели инструментов выберите запуск триггера>.

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

Вы должны получить сообщение электронной почты по указанному адресу. Кроме того, можно использовать действие "Получить сообщение электронной почты", чтобы проверить состояние отправки сообщений электронной почты с помощью действия "Отправить электронную почту ". Дополнительные действия см. в справочной документации по соединителю электронной почты Службы коммуникации Azure.

Очистка ресурсов рабочего процесса

Чтобы очистить ресурс приложения логики, рабочий процесс и связанные ресурсы, ознакомьтесь с тем, как очистить ресурсы приложения логики потребления или как очистить ресурсы приложения логики уровня "Стандартный".

Устранение неполадок

Доставка электронной почты

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

Внимание

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

Регулирование электронной почты

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

Примечание.

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

Очистка ресурсов Службы коммуникации Azure

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

Следующие шаги

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