Partilhar via

Enviar solicitações de API de desativação com API (HMAC)

  • Artigo

Este artigo descreve como habilitar o gerenciamento de exclusão para seu recurso dos Serviços de Comunicação do Azure usando a autenticação baseada em código de autenticação de mensagem hash (HMAC).

Guia de início rápido: enviar solicitações de API de desativação com API (HMAC)

O envio de uma solicitação de API de desativação é semelhante ao SMS, conforme descrito no Tutorial do Carteiro dos Serviços de Comunicação do Azure, com a diferença de pontos de extremidade para Ações de Desativação (Adicionar, Remover ou Verificar) e corpo. O corpo da solicitação tem a mesma estrutura para todas as ações, enquanto o conteúdo da resposta difere ligeiramente.

Pontos finais

Ação Ponto final
Adicionar {{endpoint}}/sms/optouts:add?api-version=2024-12-10-preview
Remover {{endpoint}}/sms/optouts:remove?api-version=2024-12-10-preview
Marcar {{endpoint}}/sms/optouts:check?api-version=2024-12-10-preview

Aqui estão alguns exemplos em diferentes idiomas.

Pedido de amostra

Cabeçalhos do pedido

Cabeçalho Value
Tipo de Conteúdo application/json
data-ms x Qui, 10 Aug 2023 12:39:55 GMT
x-ms-content-sha256 JKUqoPANwVA55u/NOCsS0Awa4cYrKKNtBwUqoaqrob0=
Autorização HMAC-SHA256 SignedHeaders=x-ms-date; anfitrião; x-ms-content-sha256&Signature=IMbd3tE3nOgEkeUQGng6oQew5aEcrZJQqHkyq8qsbLg=

Corpo do pedido

{
    "from": "+15551234567",
    "recipients": [
        {
            "to": "+15550112233"
        },
        {
            "to": "+15550112234"
        }
    ]
}

Resposta da amostra

Em geral, o conteúdo da resposta é o mesmo para todas as ações e contém o sucesso ou falha HttpStatusCode por destinatário. A única diferença é que a Check ação, que também retorna a isOptedOut bandeira.

Estado da resposta

  • 200 Ok

Adicionar corpo de resposta da ação OptOut

{
    "value": [
        {
            "to": "+15550112233",
            "httpStatusCode": 200
        },
        {
            "to": "+15550112234",
            "httpStatusCode": 200
        }
    ]
}

Remover o corpo da resposta da ação OptOut

{
    "value": [
        {
            "to": "+15550112233",
            "httpStatusCode": 200
        },
        {
            "to": "+15550112234",
            "httpStatusCode": 200
        }
    ]
}

Verifique o corpo de resposta da ação OptOut

{
    "value": [
        {
            "to": "+15550112233",
            "httpStatusCode": 200,
            "isOptedOut": true
        },
        {
            "to": "+15550112234",
            "httpStatusCode": 200,
            "isOptedOut": false
        }
    ]
}

Código de exemplo

Comece a usar a API de desativação por SMS dos Serviços de Comunicação do Azure aplicando o seguinte código de exemplo em C#.

Pré-requisitos

  • Uma conta do Azure com uma subscrição ativa. Crie uma conta gratuitamente.
  • A versão do SDK do .NET Core deve ser superior à v6 para seu sistema operacional.
  • Um recurso ativo dos Serviços de Comunicação e uma cadeia de conexão. Consulte Criar um recurso de Serviços de Comunicação.
  • Um número de telefone compatível com SMS. Consulte Obter um número de telefone.

Código de exemplo para usar a API de desativação

Este exemplo demonstra como usar a API de gerenciamento de desativação em C# para adicionar, remover ou verificar entradas de exclusão programaticamente.

using System.Globalization;
using System.Security.Cryptography;
using System.Text;

// Sample for Add action. Replace with Check or Remove as necessary.
async Task SendOptOutAdd(string acsResourceConnectionString, string payload)
{
    const string ApiPrivatePreviewVersion = "2024-12-10-preview";

    const string dateHeader = "x-ms-date";

    string accesskey = GetConnectionStringPart(acsResourceConnectionString, "accesskey");
    var endpointUri = new Uri(GetConnectionStringPart(acsResourceConnectionString, "endpoint"));

    using var httpClient = new HttpClient();
    httpClient.BaseAddress = endpointUri;

    string method = "POST";
    string baseAddress = httpClient.BaseAddress.ToString().TrimEnd('/');
    var requestUri = new Uri($"{baseAddress}/sms/optouts:add?api-version={ApiPrivatePreviewVersion }", UriKind.RelativeOrAbsolute);
    string hashedBody = ComputeSha256Hash(payload);
    string utcNowString = DateTimeOffset.UtcNow.ToString("r", CultureInfo.InvariantCulture);
    string stringToSign = $"{method}\n{requestUri.PathAndQuery}\n{utcNowString};{requestUri.Host};{hashedBody}";
    string signature = ComputeHmacSha256Hash(accesskey, stringToSign);
    string authHeader = $"HMAC-SHA256 SignedHeaders={dateHeader};host;x-ms-content-sha256&Signature={signature}";

    using HttpRequestMessage request = new();
    request.Headers.TryAddWithoutValidation(dateHeader, utcNowString);
    request.Headers.TryAddWithoutValidation("x-ms-content-sha256", hashedBody);
    request.Headers.TryAddWithoutValidation("Authorization", authHeader);
    request.RequestUri = requestUri;
    request.Method = new HttpMethod(method);
    request.Content = new StringContent(payload, Encoding.UTF8, "application/json");

    HttpResponseMessage response = await httpClient.SendAsync(request, HttpCompletionOption.ResponseHeadersRead);

    Console.WriteLine(response.StatusCode);
    Console.WriteLine(await response.Content.ReadAsStringAsync());
    Console.WriteLine(response.Headers.ToString());
}

string ComputeSha256Hash(string rawData)
{
    using SHA256 sha256Hash = SHA256.Create();
    byte[] bytes = sha256Hash.ComputeHash(Encoding.UTF8.GetBytes(rawData));
    return Convert.ToBase64String(bytes);
}

string ComputeHmacSha256Hash(string key, string rawData)
{
    using HMACSHA256 hmacSha256 = new HMACSHA256(Convert.FromBase64String(key));
    byte[] bytes = hmacSha256.ComputeHash(Encoding.ASCII.GetBytes(rawData));
    return Convert.ToBase64String(bytes);
}

string GetConnectionStringPart(string acsResourceConnectionString, string key)
{
    return acsResourceConnectionString.Split($"{key}=").Last().Split(';').First();
}

// Usage

const string ConnectionString = "endpoint=https://[CONTOSO].communication.azure.com/;accesskey=******";
var payload = System.Text.Json.JsonSerializer.Serialize(new
{
    from = "+15551234567", //replace with your allowed sender number
    recipients = new[] {
        new { to = "+15550112233" } //replace with your recipient
    },
});

await SendOptOutAdd(ConnectionString, payload);

Introdução à API de desativação de SMS dos Serviços de Comunicação do Azure usando o seguinte código de exemplo JavaScript.

Pré-requisitos

  • Uma conta do Azure com uma subscrição ativa. Crie uma conta gratuitamente.
  • Navegador ou Node.js Ative LTS e versões LTS de manutenção (8.11.1 e 10.14.1 são recomendadas).
  • Um recurso ativo dos Serviços de Comunicação e uma cadeia de conexão. Consulte Criar um recurso de Serviços de Comunicação.
  • Um número de telefone compatível com SMS. Consulte Obter um número de telefone.
  • CryptoJS é uma implementação JavaScript de algoritmos criptográficos padrão e seguros.

Código de exemplo para usar a API de desativação

Este exemplo demonstra como usar a API de gerenciamento de desativação em JavaScript para adicionar, remover ou verificar entradas de exclusão programaticamente.

<script src="Scripts/CryptoJS/sha256-min.js" type="text/javascript"></script>
<script src="Scripts/CryptoJS/hmac-sha256.js" type="text/javascript"></script>
<script src="Scripts/CryptoJS/enc-base64-min.js" type="text/javascript"></script>


const ConnectionString = "endpoint=https://[CONTOSO].communication.azure.com/;accesskey=******";

// Sample for Add action. Replace with Check or Remove as necessary.
function sendOptOutAdd(acsResourceConnectionString, payload, apiVersion = "2024-12-10-preview")
{
    try
    {
        var acsRCS = acsResourceConnectionString
            .split(";")
            .map(i =>
            {
                var p = i.indexOf("=");
                return [i.substr(0, p), i.substr(p + 1)];
            })
            .reduce((a, i) => ({ ...a, [i[0]]: i[1] }), {});
        var uri = `${trimEnd(acsRCS.endpoint, "/")}/sms/optouts:add?api-version=${apiVersion}`;
        var url = new URL(uri);
        var method = "POST";
        var utcNow = new Date().toUTCString();
        var bodyJson = JSON.stringify(payload);
        var hashedBody = CryptoJS.SHA256(bodyJson).toString(CryptoJS.enc.Base64);
        var stringToSign = `${method}\n${url.pathname}${url.search}\n${utcNow};${url.host};${hashedBody}`;
        var signature = CryptoJS.HmacSHA256(stringToSign, CryptoJS.enc.Base64.parse(acsRCS.accesskey)).toString(CryptoJS.enc.Base64);

        fetch(uri, {
            method: method,
            headers: {
                "content-type": "application/json",
                "x-ms-date": utcNow,
                "x-ms-content-sha256": hashedBody,
                Authorization: `HMAC-SHA256 SignedHeaders=x-ms-date;host;x-ms-content-sha256&Signature=${signature}`
            },
            body: bodyJson
        })
        .then(response => response.json())
        .then(console.warn)
        .catch(console.error);
    }
    catch (ex)
    {
        console.error(ex);
    }
}

function trimEnd(s, c)
{
    while (s.slice(-1) == c)
        s = s.slice(0, -1);
    return s;
}

// Usage

var payload = {
    from: "+15551234567",
    recipients: [
        { to: "+15550112233" }
    ],
};

sendOptOutAdd(ConnectionString, payload);

Comece a usar a API de desativação por SMS dos Serviços de Comunicação do Azure aplicando o seguinte código de exemplo Java.

Pré-requisitos

  • Uma conta do Azure com uma subscrição ativa. Crie uma conta gratuitamente.
  • Java Development Kit (JDK) versão 8 ou superior.
  • Um recurso ativo dos Serviços de Comunicação e uma cadeia de conexão. Consulte Criar um recurso de Serviços de Comunicação.
  • Um número de telefone compatível com SMS. Consulte Obter um número de telefone.

Código de exemplo para usar a API de desativação

Este exemplo demonstra como usar a API de gerenciamento de desativação em Java para adicionar, remover ou verificar entradas de exclusão programaticamente.

// Sample for Add action. Replace with Check or Remove as necessary.
public class App
{
    public static void main(String[] args) throws Exception
    {
        String connectionString = "endpoint=https://[CONTOSO].communication.azure.com/;accesskey=******";

        OptOutRequest payload = new OptOutRequest();
        payload.from = "+15551234567";
        payload.recipients = new ArrayList<Recipient>();
        payload.recipients.add(new Recipient("+15550112233"));

        SendOptOut(connectionString, payload);
    }

    public static void SendOptOutAdd(String connectionString, OptOutRequest payload) throws Exception
    {
        String apiVersion = "2024-12-10-preview";

        String[] arrOfStr = connectionString.split(";");
        String endpoint = arrOfStr[0].split("=")[1];
        String accessKey = arrOfStr[1].split("=")[1];
        String body = new ObjectMapper().enable(SerializationFeature.INDENT_OUTPUT).writeValueAsString(payload);
        String dateHeaderName = "x-ms-date";
        DateTimeFormatter headerDateFormat = DateTimeFormatter.ofPattern("EEE, dd MMM yyyy HH:mm:ss z", Locale.ENGLISH).withZone(ZoneId.of("GMT"));
        String dateHeader = headerDateFormat.format(Instant.now());
        String verb = "POST";
        URI uri = URI.create(endpoint + "sms/optouts:add?api-version==" + apiVersion);
        String hostName = uri.getHost();
        String pathAndQuery = uri.getPath() + "?" + uri.getQuery();
        String encodedHash = Base64.getEncoder().encodeToString(MessageDigest.getInstance("SHA-256").digest(body.getBytes(StandardCharsets.UTF_8)));
        String stringToSign = verb + '\n' + pathAndQuery + '\n' + dateHeader + ';' + hostName + ';' + encodedHash;
        Mac mac = Mac.getInstance("HmacSHA256");
        SecretKeySpec secretKeySpec = new SecretKeySpec(Base64.getDecoder().decode(accessKey.getBytes()), "HmacSHA256"); 
        mac.init(secretKeySpec);
        String signature = Base64.getEncoder().encodeToString(mac.doFinal(stringToSign.getBytes()));
        String authHeader = "HMAC-SHA256 SignedHeaders=" + dateHeaderName + ";host;x-ms-content-sha256&Signature=" + signature;

        HttpClient client = HttpClients.custom().build();
        HttpUriRequest request = RequestBuilder
            .post(uri)
            .setHeader(HttpHeaders.CONTENT_TYPE, "application/json")
            .setHeader(dateHeaderName, dateHeader)
            .setHeader("x-ms-content-sha256", encodedHash)
            .setHeader("Authorization", authHeader)
            .setEntity(new StringEntity(body, "UTF-8"))
            .build();
        HttpResponse r = client.execute(request);
        HttpEntity entity = r.getEntity();
    }
}

public class OptOutRequest
{
    public String from;
    public ArrayList<Recipient> recipients;
}

public class Recipient
{
    public String to;
}

Próximos passos

Neste guia de início rápido, você aprendeu como enviar solicitações de exclusão.

Enviar uma mensagem SMS

Receber e responder a SMS

Habilite a análise de SMS

Tipos de número de telefone

Procurar informações do operador para obter um número de telefone