Odesílání požadavků rozhraní API OptOut pomocí rozhraní API (HMAC)

Článek
12/18/2024

Tento článek popisuje, jak povolit správu odhlášení pro prostředek služby Azure Communication Services pomocí ověřovacího kódu HMAC (hash message Authentication Code).

Rychlý start: Odesílání požadavků rozhraní API OptOut pomocí rozhraní API (HMAC)

Odeslání požadavku rozhraní API pro odhlášení se podobá sms, jak je popsáno v kurzu Postman služby Azure Communication Services s rozdílem koncových bodů pro OptOut Actions (Přidání, odebrání nebo kontrola) a textu. Tělo požadavku má stejnou strukturu pro všechny akce, zatímco obsah odpovědi se mírně liší.

Koncové body

Akce	Koncový bod
Přidání	`{{endpoint}}/sms/optouts:add?api-version=2024-12-10-preview`
Odebrat	`{{endpoint}}/sms/optouts:remove?api-version=2024-12-10-preview`
Zaškrtnout	`{{endpoint}}/sms/optouts:check?api-version=2024-12-10-preview`

Tady je několik příkladů v různých jazycích.

Ukázkový požadavek

Záhlaví žádosti

Hlavička	Hodnota
Content-Type	application/json
x-ms-date	Čt, 10. 10. 2023 12:39:55 GMT
x-ms-content-sha256	JKUqoPANwVA55u/NOCsS0Awa4cYrKKNtBwUqoaqrob0=
Autorizace	HMAC-SHA256 SignedHeaders=x-ms-date; hostitel; x-ms-content-sha256&Signature=IMbd3tE3nOgEkeUQGng6oQew5aEcrZJQqHkyq8qsbLg=

Text požadavku

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

Ukázková odpověď

Obecně platí, že obsah odpovědi je stejný pro všechny akce a obsahuje úspěch nebo neúspěch HttpStatusCode na příjemce. Jediným rozdílem je, že Check akce, která také vrací isOptedOut příznak.

Stav odpovědi

200 Ok

Přidání textu odpovědi akce OptOut

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

Odebrání textu odpovědi akce OptOut

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

Kontrola textu odpovědi akce OptOut

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

Ukázkový kód

Začněte používat rozhraní API pro odhlášení sms služby Azure Communication Services s využitím následujícího vzorového kódu jazyka C#.

Požadavky

Účet Azure s aktivním předplatným. Vytvoření účtu zdarma
Verze sady .NET Core SDK musí být vyšší než verze 6 pro váš operační systém.
Aktivní prostředek služby Communication Services a připojovací řetězec. Viz Vytvoření prostředku komunikační služby.
Telefonní číslo s povolenou sms zprávou. Viz Získání telefonního čísla.

Ukázkový kód pro použití rozhraní API pro odhlášení

Tato ukázka ukazuje, jak pomocí rozhraní API opt-Out Management v jazyce C# programově přidávat, odebírat nebo kontrolovat položky odhlášení.

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

Začněte s rozhraním API pro odhlášení sms služby Azure Communication Services s využitím následujícího ukázkového kódu JavaScriptu.

Požadavky

Účet Azure s aktivním předplatným. Vytvoření účtu zdarma
Doporučuje se prohlížeč nebo Node.js verze ACTIVE LTS a maintenance LTS (8.11.1 a 10.14.1).
Aktivní prostředek služby Communication Services a připojovací řetězec. Viz Vytvoření prostředku komunikační služby.
Telefonní číslo s povolenou sms zprávou. Viz Získání telefonního čísla.
CryptoJS je javascriptové implementace standardních a zabezpečených kryptografických algoritmů.

Ukázkový kód pro použití rozhraní API pro odhlášení

Tato ukázka ukazuje, jak pomocí rozhraní API pro správu odhlášení v JavaScriptu programově přidávat, odebírat nebo kontrolovat položky odhlášení.

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

Začněte s rozhraním API pro odhlášení SMS služby Azure Communication Services s využitím následujícího ukázkového kódu v Javě.

Požadavky

Účet Azure s aktivním předplatným. Vytvoření účtu zdarma
Java Development Kit (JDK) verze 8 nebo novější.
Aktivní prostředek služby Communication Services a připojovací řetězec. Viz Vytvoření prostředku komunikační služby.
Telefonní číslo s povolenou sms zprávou. Viz Získání telefonního čísla.

Ukázkový kód pro použití rozhraní API pro odhlášení

Tato ukázka ukazuje, jak pomocí rozhraní API opt-Out Management v Javě programově přidávat, odebírat nebo kontrolovat položky odhlášení.

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