Comunicação: Enviando emails e mensagens SMS

Além de chamadas telefônicas, os Serviços de Comunicação do Azure também podem enviar mensagens de email e SMS. Isso pode ser útil quando você deseja enviar uma mensagem para um cliente ou outro usuário diretamente do aplicativo.

Neste exercício, você vai:

• Explore como as mensagens de e-mail e SMS podem ser enviadas a partir do aplicativo.
• Percorra o código para saber como a funcionalidade de email e SMS é implementada.

Usando os recursos de e-mail e SMS

1. Em um exercício anterior , você criou um recurso dos Serviços de Comunicação do Azure (ACS) e iniciou o banco de dados, o servidor Web e o servidor de API. Você também atualizou os seguintes valores no arquivo .env .

   ACS_CONNECTION_STRING=<ACS_CONNECTION_STRING>
   ACS_PHONE_NUMBER=<ACS_PHONE_NUMBER>
   ACS_EMAIL_ADDRESS=<ACS_EMAIL_ADDRESS>
   CUSTOMER_EMAIL_ADDRESS=<EMAIL_ADDRESS_TO_SEND_EMAIL_TO>
   CUSTOMER_PHONE_NUMBER=<UNITED_STATES_BASED_NUMBER_TO_SEND_SMS_TO>
   

   Verifique se você concluiu o exercício anterior antes de continuar.

2. Volte para o navegador (http://localhost:4200) e selecione Contatar Cliente seguido pelo Cliente de Email/SMS na primeira linha.

   

3. Selecione a guia Email/SMS e execute as seguintes tarefas:

   • Insira uma Entidade de Email e Corpo e selecione o botão Enviar Email .
   • Insira uma mensagem SMS e selecione o botão Enviar SMS .

   

   Observação

   A verificação por SMS para números gratuitos agora é obrigatória nos Estados Unidos e no Canadá. Para ativar as mensagens SMS, você deve enviar a verificação após a compra do número de telefone. Embora este tutorial não passe por esse processo, você pode selecionar Telefonia e SMS -->Documentos Regulatórios do recurso dos Serviços de Comunicação do Azure no portal do Azure e adicionar a documentação de validação necessária.

4. Verifique se você recebeu o e-mail e as mensagens SMS. A funcionalidade SMS só funcionará se você tiver enviado os documentos regulamentares mencionados na nota anterior. Como lembrete, a mensagem de email será enviada para o valor definido CUSTOMER_EMAIL_ADDRESS e a mensagem SMS será enviada para o valor definido CUSTOMER_PHONE_NUMBER no arquivo .env . Se você não conseguiu fornecer um número de telefone baseado nos Estados Unidos para usar em mensagens SMS, pode pular essa etapa.

   Observação

   Se você não vir a mensagem de email em sua caixa de entrada para o endereço definido CUSTOMER_EMAIL_ADDRESS no arquivo .env , verifique sua pasta de spam.

Explorando o código de e-mail

1. Abra o arquivo customers-list.component.ts . O caminho completo para o arquivo é client/src/app/customers-list/customers-list.component.ts.

2. Quando você selecionou o Cliente de Contato seguido pelo Cliente de Email/SMS no datagrid, o customer-list componente exibiu uma caixa de diálogo. Isso é tratado pela openEmailSmsDialog() função no arquivo customer-list.component.ts .

   openEmailSmsDialog(data: any) {
       if (data.phone && data.email) {
           // Create the data for the dialog
           let dialogData: EmailSmsDialogData = {
               prompt: '',
               title: `Contact ${data.company}`,
               company: data.company,
               customerName: data.first_name + ' ' + data.last_name,
               customerEmailAddress: data.email,
               customerPhoneNumber: data.phone
           }
   
           // Open the dialog
           const dialogRef = this.dialog.open(EmailSmsDialogComponent, {
               data: dialogData
           });
   
           // Subscribe to the dialog afterClosed observable to get the dialog result
           this.subscription.add(
               dialogRef.afterClosed().subscribe((response: EmailSmsDialogData) => {
                   console.log('SMS dialog result:', response);
                   if (response) {
                       dialogData = response;
                   }
               })
           );
       }
       else {
           alert('No phone number available.');
       }
   }
   

   A openEmailSmsDialog() função executa as seguintes tarefas:

   • Verifica se o data objeto (que representa a linha da grade de dados) contém uma phone propriedade and email . Em caso afirmativo, ele cria um dialogData objeto que contém as informações a serem passadas para a caixa de diálogo.
   • Abre a EmailSmsDialogComponent caixa de diálogo e passa o dialogData objeto para ela.
   • Assina o afterClosed() evento da caixa de diálogo. Esse evento é acionado quando a caixa de diálogo é fechada. O response objeto contém as informações que foram inseridas na caixa de diálogo.

3. Abra o arquivo de email-sms-dialog.component.ts . O caminho completo para o arquivo é client/src/app/email-sms-dialog/email-sms-dialog.component.ts.

4. Localize a sendEmail() função:

   sendEmail() {
       if (this.featureFlags.acsEmailEnabled) {
           // Using CUSTOMER_EMAIL_ADDRESS instead of this.data.email for testing purposes
           this.subscription.add(
               this.acsService.sendEmail(this.emailSubject, this.emailBody, 
                   this.getFirstName(this.data.customerName), CUSTOMER_EMAIL_ADDRESS /* this.data.email */)
               .subscribe(res => {
                   console.log('Email sent:', res);
                   if (res.status) {
                       this.emailSent = true;
                   }
               })
           );
       }
       else {
           this.emailSent = true; // Used when ACS email isn't enabled
       }
   }
   

   A sendEmail() função executa as seguintes tarefas:

   • Verifica se o sinalizador de acsEmailEnabled recurso está definido como true. Esse sinalizador verifica se a ACS_EMAIL_ADDRESS variável de ambiente tem um valor atribuído.
   • Se acsEmailEnabled for true, a função será chamada e o assunto, o acsService.sendEmail() corpo, o nome do cliente e o endereço de email do cliente serão passados. Como o banco de dados contém dados de amostra, a CUSTOMER_EMAIL_ADDRESS variável de ambiente é usada em vez de this.data.email. Em um aplicativo do mundo real, o this.data.email valor seria usado.
   • Subscreve a sendEmail() função no acsService serviço. Essa função retorna um RxJS observável que contém a resposta do serviço do lado do cliente.
   • Se o e-mail foi enviado com êxito, a emailSent propriedade é definida como true.

5. Para fornecer melhor encapsulamento e reutilização de código, serviços do lado do cliente, como acs.service.ts são usados em todo o aplicativo. Isso permite que todas as funcionalidades do ACS sejam consolidadas em um único local.

6. Abra acs.service.ts e localize a sendEmail() função. O caminho completo para o arquivo é client/src/app/core/acs.service.ts.

   sendEmail(subject: string, message: string, customerName: string, customerEmailAddress: string) : Observable<EmailSmsResponse> {
       return this.http.post<EmailSmsResponse>(this.apiUrl + 'sendEmail', { subject, message, customerName, customerEmailAddress })
       .pipe(
           catchError(this.handleError)
       );
   }
   

   A sendEmail() função em AcsService executa as seguintes tarefas:

   • Chama a http.post() função e passa o assunto do email, a mensagem, o nome do cliente e o endereço de email do cliente para ela. A http.post() função retorna um observável RxJS que contém a resposta da chamada à API.
   • Manipula todos os http.post() erros retornados pela função usando o operador RxJS catchError .

7. Agora vamos examinar como o aplicativo interage com o recurso de e-mail do ACS. Abra o arquivo acs.ts e localize a sendEmail() função. O caminho completo para o arquivo é server/typescript/acs.ts.

8. A sendEmail() função executa as seguintes tarefas:

   • Cria um novo EmailClient objeto e passa a cadeia de conexão ACS para ele (esse valor é recuperado da ACS_CONNECTION_STRING variável de ambiente).

     const emailClient = new EmailClient(connectionString);
     

   • Cria um novo EmailMessage objeto e passa as informações do remetente, assunto, mensagem e destinatário.

     const msgObject: EmailMessage = {
         senderAddress: process.env.ACS_EMAIL_ADDRESS as string,
         content: {
             subject: subject,
             plainText: message,
         },
         recipients: {
             to: [
                 {
                     address: customerEmailAddress,
                     displayName: customerName,
                 },
             ],
         },
     };
     

   • Envia o e-mail usando a emailClient.beginSend() função e retorna a resposta. Embora a função esteja enviando apenas para um destinatário neste exemplo, a beginSend() função também pode ser usada para enviar para vários destinatários.

     const poller = await emailClient.beginSend(msgObject);
     

   • Aguarda que o poller objeto sinalize que foi concluído e envia a resposta ao chamador.

Explorando o código SMS

1. Volte para o arquivo de email-sms-dialog.component.ts que você abriu anteriormente. O caminho completo para o arquivo é client/src/app/email-sms-dialog/email-sms-dialog.component.ts.

2. Localize a sendSms() função:

   sendSms() {
       if (this.featureFlags.acsPhoneEnabled) {
           // Using CUSTOMER_PHONE_NUMBER instead of this.data.customerPhoneNumber for testing purposes
           this.subscription.add(
               this.acsService.sendSms(this.smsMessage, CUSTOMER_PHONE_NUMBER /* this.data.customerPhoneNumber */)
                 .subscribe(res => {
                   if (res.status) {
                       this.smsSent = true;
                   }
               })
           );
       }
       else {
           this.smsSent = true;
       }
   }
   

   A sendSMS() função executa as seguintes tarefas:

   • Verifica se o sinalizador de acsPhoneEnabled recurso está definido como true. Esse sinalizador verifica se a ACS_PHONE_NUMBER variável de ambiente tem um valor atribuído.
   • Se acsPhoneEnabled for true, a acsService.SendSms() função será chamada e a mensagem SMS e o número de telefone do cliente serão passados. Como o banco de dados contém dados de amostra, a CUSTOMER_PHONE_NUMBER variável de ambiente é usada em vez de this.data.customerPhoneNumber. Em um aplicativo do mundo real, o this.data.customerPhoneNumber valor seria usado.
   • Subscreve a sendSms() função no acsService serviço. Essa função retorna um RxJS observável que contém a resposta do serviço do lado do cliente.
   • Se a mensagem SMS foi enviada com êxito, ela define a smsSent propriedade como true.

3. Abra acs.service.ts e localize a sendSms() função. O caminho completo para o arquivo é client/src/app/core/acs.service.ts.

   sendSms(message: string, customerPhoneNumber: string) : Observable<EmailSmsResponse> {
       return this.http.post<EmailSmsResponse>(this.apiUrl + 'sendSms', { message, customerPhoneNumber })
       .pipe(
           catchError(this.handleError)
       );
   }  
   

   A sendSms() função executa as seguintes tarefas:

   • Chama a http.post() função e passa a mensagem e o número de telefone do cliente para ela. A http.post() função retorna um observável RxJS que contém a resposta da chamada à API.
   • Manipula todos os http.post() erros retornados pela função usando o operador RxJS catchError .

4. Por fim, vamos examinar como o aplicativo interage com o recurso ACS SMS. Abra o arquivo acs.ts . O caminho completo para o arquivo é servidor/typescript/acs.ts e localiza a sendSms() função.

5. A sendSms() função executa as seguintes tarefas:

   • Cria um novo SmsClient objeto e passa a cadeia de conexão ACS para ele (esse valor é recuperado da ACS_CONNECTION_STRING variável de ambiente).

     const smsClient = new SmsClient(connectionString);
     

   • Chama a smsClient.send() função e passa o número de telefone do ACS (from), o número de telefone do cliente (to) e a mensagem SMS:

     const sendResults = await smsClient.send({
         from: process.env.ACS_PHONE_NUMBER as string,
         to: [customerPhoneNumber],
         message: message
     });
     return sendResults;
     

   • Retorna a resposta ao chamador.

6. Você pode saber mais sobre a funcionalidade de e-mail e SMS do ACS nos seguintes artigos:

   • Email nos Serviços de Comunicação do Azure
   • SMS nos Serviços de Comunicação do Azure

7. Antes de passar para o próximo exercício, vamos examinar os principais conceitos abordados neste exercício:

   • O arquivo acs.service.ts encapsula a funcionalidade de email e SMS do ACS usada pelo aplicativo do lado do cliente. Ele lida com as chamadas de API para o servidor e retorna a resposta para o chamador.
   • A API do lado do servidor usa o ACS EmailClient e SmsClient objetos para enviar mensagens de email e SMS.

8. Agora que você aprendeu como as mensagens de email e SMS podem ser enviadas, vamos mudar nosso foco para a integração de dados organizacionais no aplicativo.

Próxima Etapa