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

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

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

• Учетная запись Azure с активной подпиской. Создайте учетную запись бесплатно .
• Последняя версия клиентской библиотеки NET Core для вашей операционной системы.
• Созданный и готовый ресурс служб коммуникации электронной почты Azure для подготовки домена Начало работы с помощью создания ресурса Коммуникации электронной почты
• Активный ресурс служб коммуникации, подключенный к домену электронной почты. Начало работы путем подключения Службы коммуникации электронной почты к ресурсу Службы коммуникации

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

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

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

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

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

   

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

   

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

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

   

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

   

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

   

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

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

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

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

     

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

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

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

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

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

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

• В окне терминала или командной строки выполните 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>"

export AZURE_COMMUNICATION_CONNECTION_STRING="<connectionString>"

export AZURE_COMMUNICATION_CONNECTION_STRING="<connectionString>"

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

az communication email send
	--connection-string "yourConnectionString"
	--sender "<[email protected]>"
	--to "<[email protected]>"
	--subject "Welcome to Azure Communication Services Email" --text "This email message is sent from Azure Communication Services Email using Azure CLI." 

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

• Замените <yourConnectionString> строка подключения.
• Замените <[email protected]> адрес электронной почты, на который вы хотите отправить сообщение.
• Замените <[email protected]> адрес MailFrom проверенного домена.

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

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

Следующие необязательные параметры доступны в 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# для отправки сообщений электронной почты.

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

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

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

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

• Учетная запись Azure с активной подпиской. Создайте учетную запись бесплатно .
• Последняя версия клиентской библиотеки NET Core для вашей операционной системы.
• Созданный и готовый ресурс служб коммуникации электронной почты 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)
    {

    }
  }
}

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

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

dotnet add package Azure.Identity

// This code demonstrates how to authenticate to your Communication Service resource using
// DefaultAzureCredential and the environment variables AZURE_CLIENT_ID, AZURE_TENANT_ID,
// and AZURE_CLIENT_SECRET.
string resourceEndpoint = "<ACS_RESOURCE_ENDPOINT>";
EmailClient emailClient = new EmailClient(new Uri(resourceEndpoint), new DefaultAzureCredential());

var key = new AzureKeyCredential("<your-key-credential>");
var endpoint = new Uri("<your-endpoint-uri>");

var emailClient = new EmailClient(endpoint, key);

//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 = "[email protected]";
var recipient = "[email protected]";

/// 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

//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 = "[email protected]";
var recipient = "[email protected]";

try
{
    Console.WriteLine("Sending email...");
    EmailSendOperation emailSendOperation = await emailClient.SendAsync(
        Azure.WaitUntil.Completed,
        sender,
        recipient,
        subject,
        htmlContent);
    EmailSendResult statusMonitor = emailSendOperation.Value;

    Console.WriteLine($"Email Sent. Status = {emailSendOperation.Value.Status}");

    /// 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}");
}
catch (RequestFailedException ex)
{
    /// OperationID is contained in the exception message and can be used for troubleshooting purposes
    Console.WriteLine($"Email send operation failed with error code: {ex.ErrorCode}, message: {ex.Message}");
}

dotnet run

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

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

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

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

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

• Node.js (~14).
• Учетная запись Azure с активной подпиской. Создайте учетную запись бесплатно .
• Ресурс Служб коммуникации Электронной почты Azure, созданный и готовый с подготовленным доменом. Начало работы с созданием ресурса обмена сообщениями электронной почты.
• Активный Службы коммуникации Azure ресурс, подключенный к домену электронной почты и его строка подключения. Начало работы с подключением ресурса обмена сообщениями электронной почты с помощью ресурса коммуникации Azure.

Выполнение этого краткого руководства предполагает небольшую дополнительную плату в несколько центов США в учетной записи 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.

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

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

npm install dotenv

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

npm install @azure/identity

import { DefaultAzureCredential } from "@azure/identity";
import { EmailClient } from "@azure/communication-email";

const endpoint = "https://<resource-name>.communication.azure.com";
let credential = new DefaultAzureCredential();

const emailClient = new EmailClient(endpoint, credential);

const { EmailClient, KnownEmailSendStatus } = require("@azure/communication-email");
const { AzureKeyCredential } = require("@azure/core-auth");
require("dotenv").config();

var key = new AzureKeyCredential("<your-key-credential>");
var endpoint = "<your-endpoint-uri>";

const emailClient = new EmailClient(endpoint, key);

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

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

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

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

async function main() {
  const POLLER_WAIT_TIME = 10
  try {
    const message = {
      senderAddress: "<[email protected]>",
      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: "<[email protected]>",
            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();

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

• Замените <[email protected]> адрес электронной почты, на который вы хотите отправить сообщение.
• Замените <[email protected]> адрес MailFrom проверенного домена.

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

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

node ./send-email.js

Пример кода

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

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

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

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

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

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

• Учетная запись Azure с активной подпиской. Создайте учетную запись бесплатно .
• комплект SDK для Java (JDK) версии 8 или более поздней версии.
• Apache Maven.
• Развернутый ресурс Служб коммуникации и строка подключения. Дополнительные сведения см. в разделе "Создание ресурса служб коммуникации".
• Создайте ресурс Служб коммуникации 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.
    }
}

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

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

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

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

// You can find your endpoint and access key from your resource in the Azure portal
String endpoint = "https://<resource-name>.communication.azure.com/";
EmailClient emailClient = new EmailClientBuilder()
    .endpoint(endpoint)
    .credential(new DefaultAzureCredentialBuilder().build())
    .buildClient();

// You can find your endpoint and access key from your resource in the Azure portal
String endpoint = "https://<resource-name>.communication.azure.com/";
EmailAsyncClient emailClient = new EmailClientBuilder()
    .endpoint(endpoint)
    .credential(new DefaultAzureCredentialBuilder().build())
    .buildAsyncClient();

String endpoint = "https://<resource-name>.communication.azure.com";
AzureKeyCredential azureKeyCredential = new AzureKeyCredential("<access-key>");
EmailClient emailClient = new EmailClientBuilder()
    .endpoint(endpoint)
    .credential(azureKeyCredential)
    .buildClient();

String endpoint = "https://<resource-name>.communication.azure.com";
AzureKeyCredential azureKeyCredential = new AzureKeyCredential("<access-key>");
EmailClient emailClient = new EmailClientBuilder()
    .endpoint(endpoint)
    .credential(azureKeyCredential)
    .buildClient();

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

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

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

EmailMessage message = new EmailMessage()
    .setSenderAddress("<[email protected]>")
    .setToRecipients("<[email protected]>")
    .setSubject("Welcome to Azure Communication Services Email")
    .setBodyPlainText("This email message is sent from Azure Communication Services Email using the Java SDK.");

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

• Замените <[email protected]> адрес электронной почты, на который вы хотите отправить сообщение.
• Замените <[email protected]> адрес MailFrom проверенного домена.

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

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

PollerFlux<EmailSendResult, EmailSendResult> poller = emailAsyncClient.beginSend(emailMessage);
// The initial request is sent out as soon as we subscribe the to PollerFlux object
poller.subscribe(
        response -> {
            if (response.getStatus() == LongRunningOperationStatus.SUCCESSFULLY_COMPLETED) {
                System.out.printf("Successfully sent the email (operation id: %s)", response.getValue().getId());
            }
            else {
                System.out.println("Email send status: " + response.getStatus());
            }
        },
        error -> {
            System.out.println("Error occurred while sending email: " + error.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 для служб коммуникации для отправки сообщений электронной почты.

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

В следующем шаблоне сообщения 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 описаны далее в следующей таблице.

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

• Учетная запись Azure с активной подпиской. Создайте учетную запись бесплатно .
• Python версии 3.7 и выше.
• Ресурс Служб коммуникации Электронной почты Azure, созданный и готовый с подготовленным доменом. Начало работы с созданием ресурса обмена сообщениями электронной почты.
• Активный Службы коммуникации Azure ресурс, подключенный к домену электронной почты и его строка подключения. Начало работы с подключением ресурса обмена сообщениями электронной почты с помощью ресурса коммуникации 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

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

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

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

from azure.communication.email import EmailClient
from azure.identity import DefaultAzureCredential

# To use Azure Active Directory Authentication (DefaultAzureCredential) make sure to have AZURE_TENANT_ID, AZURE_CLIENT_ID and AZURE_CLIENT_SECRET as env variables.
endpoint = "https://<resource-name>.communication.azure.com"
email_client = EmailClient(endpoint, DefaultAzureCredential())

from azure.communication.email import EmailClient
from azure.core.credentials import AzureKeyCredential

key = AzureKeyCredential("<your-key-credential>");
endpoint = "<your-endpoint-uri>";

email_client = EmailClient(endpoint, key);

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

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

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

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

• Создайте сообщение со следующими значениями:
  • 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": "<[email protected]>",
                "displayName": "Customer Name"
            }
        ]
    },
    "senderAddress": "<[email protected]>"
}

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

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

• Замените <[email protected]> адрес электронной почты, на который вы хотите отправить сообщение.
• Замените <[email protected]> адрес 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. В списке действий выберите "Отправить сообщение электронной почты".

      

   Стандартные

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

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

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

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

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

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

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

      

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

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

   

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

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

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

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

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

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

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

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