Biblioteca de clientes do Serviço de SMS de Comunicações do Azure para Java – versão 1.1.18

Artigo
10/21/2023

O SMS de Comunicação do Azure é usado para enviar mensagens de texto simples.

Código-fonte | Pacote (Maven) | Documentação | de referência da API Documentação do produto

Introdução

Pré-requisitos

Uma conta do Azure com uma assinatura ativa. Crie uma conta gratuitamente.
JDK (Java Development Kit) versão 8 ou superior.
Apache Maven.
Um recurso dos Serviços de Comunicação implantado. Você pode usar o Portal do Azure ou o Azure PowerShell para configurá-lo.

Incluir o pacote

Incluir o arquivo da BOM

Inclua o azure-sdk-bom em seu projeto para assumir a dependência da versão ga (disponibilidade geral) da biblioteca. No trecho a seguir, substitua o espaço reservado {bom_version_to_target} pelo número de versão. Para saber mais sobre o BOM, consulte o BOM README do SDK do AZURE.

<dependencyManagement>
    <dependencies>
        <dependency>
            <groupId>com.azure</groupId>
            <artifactId>azure-sdk-bom</artifactId>
            <version>{bom_version_to_target}</version>
            <type>pom</type>
            <scope>import</scope>
        </dependency>
    </dependencies>
</dependencyManagement>

Depois, inclua a dependência direta na seção de dependências sem a marca de versão.

<dependencies>
  <dependency>
    <groupId>com.azure</groupId>
    <artifactId>azure-communication-sms</artifactId>
  </dependency>
</dependencies>

Incluir dependência direta

Se você quiser assumir a dependência de uma versão específica da biblioteca que não está presente no BOM, adicione a dependência direta ao seu projeto da seguinte maneira.

<dependency>
  <groupId>com.azure</groupId>
  <artifactId>azure-communication-sms</artifactId>
  <version>1.1.18</version>
</dependency>

Autenticar o cliente

Autenticação de Token do Azure Active Directory

Um DefaultAzureCredential objeto deve ser passado para o SmsClientBuilder por meio da função credential(). Ponto de extremidade e httpClient também devem ser definidos por meio das funções endpoint() e httpClient(), respectivamente.

AZURE_CLIENT_SECRET, AZURE_CLIENT_ID e AZURE_TENANT_ID variáveis de ambiente são necessárias para criar um objeto DefaultAzureCredential.

// You can find your endpoint and access key from your resource in the Azure Portal
String endpoint = "https://<RESOURCE_NAME>.communication.azure.com";

SmsClient smsClient = new SmsClientBuilder()
    .endpoint(endpoint)
    .credential(new DefaultAzureCredentialBuilder().build())
    .buildClient();

Autenticação de Chave de Acesso

O SMS usa a autenticação HMAC com a chave de acesso do recurso. A chave de acesso deve ser fornecida ao SmsClientBuilder por meio da função credential(). Ponto de extremidade e httpClient também devem ser definidos por meio das funções endpoint() e httpClient(), respectivamente.

// You can find your endpoint and access key from your resource in the Azure Portal
String endpoint = "https://<resource-name>.communication.azure.com";
AzureKeyCredential azureKeyCredential = new AzureKeyCredential("<access-key>");

SmsClient smsClient = new SmsClientBuilder()
    .endpoint(endpoint)
    .credential(azureKeyCredential)
    .buildClient();

Como alternativa, você pode fornecer todo o cadeia de conexão usando a função connectionString() em vez de fornecer o ponto de extremidade e a chave de acesso.

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

SmsClient smsClient = new SmsClientBuilder()
    .connectionString(connectionString)
    .buildClient();

Principais conceitos

Há duas formas diferentes de autenticação para usar o Serviço de SMS de Comunicação do Azure.

Exemplos

Enviar uma mensagem SMS 1:1

Use a send função ou sendWithResponse para enviar uma mensagem SMS para um único número de telefone.

SmsSendResult sendResult = smsClient.send(
    "<from-phone-number>",
    "<to-phone-number>",
    "Weekly Promotion");

System.out.println("Message Id: " + sendResult.getMessageId());
System.out.println("Recipient Number: " + sendResult.getTo());
System.out.println("Send Result Successful:" + sendResult.isSuccessful());

Enviar uma mensagem SMS 1:N

Para enviar uma mensagem SMS para uma lista de destinatários, chame a send função ou sendWithResponse com uma lista de números de telefone do destinatário. Você também pode adicionar passagem em um objeto de opções para especificar se o relatório de entrega deve ser habilitado e definir marcas personalizadas.

SmsSendOptions options = new SmsSendOptions();
options.setDeliveryReportEnabled(true);
options.setTag("Marketing");

Iterable<SmsSendResult> sendResults = smsClient.sendWithResponse(
    "<from-phone-number>",
    Arrays.asList("<to-phone-number1>", "<to-phone-number2>"),
    "Weekly Promotion",
    options /* Optional */,
    Context.NONE).getValue();

for (SmsSendResult result : sendResults) {
    System.out.println("Message Id: " + result.getMessageId());
    System.out.println("Recipient Number: " + result.getTo());
    System.out.println("Send Result Successful:" + result.isSuccessful());
}

Solução de problemas

As operações de SMS gerarão uma exceção se a solicitação para o servidor falhar. Exceções não serão geradas se o erro for causado por uma mensagem individual, somente se algo falhar com a solicitação geral. Use o isSuccessful() sinalizador para validar cada resultado individual para verificar se a mensagem foi enviada.

try {
    SmsSendOptions options = new SmsSendOptions();
    options.setDeliveryReportEnabled(true);
    options.setTag("Marketing");

    Response<Iterable<SmsSendResult>> sendResults = smsClient.sendWithResponse(
        "<from-phone-number>",
        Arrays.asList("<to-phone-number1>", "<to-phone-number2>"),
        "Weekly Promotion",
        options /* Optional */,
        Context.NONE);

    Iterable<SmsSendResult> smsSendResults = sendResults.getValue();
    for (SmsSendResult result : smsSendResults) {
        if (result.isSuccessful()) {
            System.out.println("Successfully sent this message: " + result.getMessageId() + " to " + result.getTo());
        } else {
            System.out.println("Something went wrong when trying to send this message " + result.getMessageId() + " to " + result.getTo());
            System.out.println("Status code " + result.getHttpStatusCode() + " and error message " + result.getErrorMessage());
        }
    }
} catch (RuntimeException ex) {
    System.out.println(ex.getMessage());
}

Próximas etapas

Leia mais sobre SMS no Serviços de Comunicação do Azure
Para obter um guia básico sobre como configurar o Relatório de Entrega para suas mensagens SMS, consulte o guia de início rápido Manipular Eventos de SMS.

Impressões

Contribuição

Este projeto aceita contribuições e sugestões. A maioria das contribuições exige que você concorde com um CLA (Contrato de Licença do Colaborador) declarando que você tem o direito de nos conceder e de fato concede, os direitos de usar sua contribuição.

Quando você envia uma solicitação de pull, um bot do CLA determina automaticamente se você precisa fornecer um CLA e preencher a PR corretamente (por exemplo, rótulo, comentário). Basta seguir as instruções fornecidas pelo bot. Você só precisará fazer isso uma vez em todos os repositórios que usam nosso CLA.

Este projeto adotou o Código de Conduta de Software Livre da Microsoft. Para obter mais informações, confira as Perguntas frequentes sobre o Código de Conduta ou contate opencode@microsoft.com para enviar outras perguntas ou comentários.

Partilhar via