Alibaba Cloud SDK：Badan permintaan dan mekanisme tanda tangan V2 untuk API bergaya RPC

Contoh parameter tetap

Contoh Java

Untuk menjalankan contoh Java, tambahkan dependensi Maven berikut ke file pom.xml Anda.

<dependency>
    <groupId>org.apache.httpcomponents</groupId>
    <artifactId>httpclient</artifactId>
    <version>4.5.13</version>
</dependency>

import org.apache.http.client.methods.*;
import org.apache.http.client.utils.URIBuilder;
import org.apache.http.entity.ByteArrayEntity;
import org.apache.http.entity.ContentType;
import org.apache.http.impl.client.CloseableHttpClient;
import org.apache.http.impl.client.HttpClients;
import org.apache.http.util.EntityUtils;

import javax.crypto.Mac;
import javax.crypto.spec.SecretKeySpec;
import java.io.IOException;
import java.io.UnsupportedEncodingException;
import java.net.URISyntaxException;
import java.net.URLEncoder;
import java.nio.charset.StandardCharsets;
import java.nio.file.Files;
import java.nio.file.Paths;
import java.security.InvalidKeyException;
import java.security.NoSuchAlgorithmException;
import java.text.SimpleDateFormat;
import java.util.*;

public class Demo {
    private static final String ACCESS_KEY_ID = System.getenv("ALIBABA_CLOUD_ACCESS_KEY_ID");
    private static final String ACCESS_KEY_SECRET = System.getenv("ALIBABA_CLOUD_ACCESS_KEY_SECRET");

    public static class SignatureRequest {
        public final String httpMethod;
        public final String host;
        public final String action;
        public final String version;
        public final String canonicalUri = "/";
        public TreeMap<String, Object> headers = new TreeMap<>();
        public TreeMap<String, Object> queryParams = new TreeMap<>();
        public TreeMap<String, Object> body = new TreeMap<>();
        public TreeMap<String, Object> allParams = new TreeMap<>();
        public byte[] bodyByte;

        public SignatureRequest(String httpMethod, String host, String action, String version) {
            this.httpMethod = httpMethod;
            this.host = host;
            this.action = action;
            this.version = version;
            setExtendedHeaders();
        }

        public void setExtendedHeaders() {
            headers.put("AccessKeyId", ACCESS_KEY_ID);
            headers.put("Format", "JSON");
            headers.put("SignatureMethod", "HMAC-SHA1");
            headers.put("SignatureVersion", "1.0");
            headers.put("SignatureNonce", UUID.randomUUID().toString());
            SimpleDateFormat format = new SimpleDateFormat("yyyy-MM-dd'T'HH:mm:ss'Z'")
            format.setTimeZone(new SimpleTimeZone(0, "GMT"));
            headers.put("Timestamp", format.format(new Date()));
            headers.put("Action", action);
            headers.put("Version", version);
        }

        public void getAllParams() {
            allParams.putAll(headers);
            if (!queryParams.isEmpty()) {
                allParams.putAll(queryParams);
            }
            if (!body.isEmpty()) {
                allParams.putAll(body);
            }
        }
    }

    public static void main(String[] args) throws IOException {
        // Contoh 1: Kirim permintaan API tanpa badan.
        String httpMethod = "POST";
        String endpoint = "dysmsapi.aliyuncs.com";
        String action = "SendSms";
        String version = "2017-05-25";
        SignatureRequest signatureRequest = new SignatureRequest(httpMethod, endpoint, action, version);
        signatureRequest.queryParams.put("PhoneNumbers", "123XXXXXXXX");
        signatureRequest.queryParams.put("SignName", "XXXXXXX");
        signatureRequest.queryParams.put("TemplateCode", "XXXXXXX");
        signatureRequest.queryParams.put("TemplateParam", "XXXXXXX");

        /*// Contoh 2: Kirim permintaan API dengan badan.
        String httpMethod = "POST";
        String endpoint = "mt.aliyuncs.com";
        String action = "TranslateGeneral";
        String version = "2018-10-12";
        SignatureRequest signatureRequest = new SignatureRequest(httpMethod, endpoint, action, version);
        TreeMap<String, Object> body = new TreeMap<>();
        body.put("FormatType", "text");
        body.put("SourceLanguage", "zh");
        body.put("TargetLanguage", "en");
        body.put("SourceText", "Hello");
        body.put("Scene", "general");
        signatureRequest.body = body;
        String formDataToString = formDataToString(body);
        signatureRequest.bodyByte = formDataToString.getBytes(StandardCharsets.UTF_8);
        signatureRequest.headers.put("content-type", "application/x-www-form-urlencoded");*/

        /*// Contoh 3: Kirim permintaan API yang badannya berupa file biner.
        String httpMethod = "POST";
        String endpoint = "ocr-api.cn-hangzhou.aliyuncs.com";
        String action = "RecognizeGeneral";
        String version = "2021-07-07";
        SignatureRequest signatureRequest = new SignatureRequest(httpMethod, endpoint, action, version);
        signatureRequest.bodyByte = Files.readAllBytes(Paths.get("D:\\test.png"));
        signatureRequest.headers.put("content-type", "application/octet-stream");*/

        // Hitung string tanda tangan.
        calculateSignature(signatureRequest);

        // Kirim permintaan untuk menguji apakah string tanda tangan valid.
        callApi(signatureRequest);
    }

    private static void calculateSignature(SignatureRequest signatureRequest) {
        // Gabungkan header, queryParam, dan body ke dalam peta yang digunakan untuk menyusun string kueri yang dinormalisasi.
        signatureRequest.getAllParams();

        // Susun string kueri yang dinormalisasi.
        StringBuilder canonicalQueryString = new StringBuilder();
        signatureRequest.allParams.entrySet().stream().map(entry -> percentEncode(entry.getKey()) + "="
                + percentEncode(String.valueOf(entry.getValue()))).forEachOrdered(queryPart -> {
            if (canonicalQueryString.length() > 0) {
                canonicalQueryString.append("&");
            }
            canonicalQueryString.append(queryPart);
        });
        System.out.println("canonicalQueryString:" + canonicalQueryString);

        // Buat string yang akan ditandatangani.
        String stringToSign = signatureRequest.httpMethod + "&" + percentEncode(signatureRequest.canonicalUri) + "&" + percentEncode(String.valueOf(canonicalQueryString));
        System.out.println("stringToSign:" + stringToSign);
        // Hitung string tanda tangan.
        String signature = generateSignature(ACCESS_KEY_SECRET, stringToSign);
        System.out.println("signature:" + signature);
        signatureRequest.allParams.put("Signature", signature);
    }

    private static void callApi(SignatureRequest signatureRequest) {
        try {
            String url = String.format("https://%s/", signatureRequest.host);
            URIBuilder uriBuilder = new URIBuilder(url);
            for (Map.Entry<String, Object> entry : signatureRequest.allParams.entrySet()) {
                uriBuilder.addParameter(entry.getKey(), String.valueOf(entry.getValue()));
            }
            HttpUriRequest httpRequest;
            switch (signatureRequest.httpMethod) {
                case "GET":
                    httpRequest = new HttpGet(uriBuilder.build());
                    break;
                case "POST":
                    HttpPost httpPost = new HttpPost(uriBuilder.build());
                    if (signatureRequest.bodyByte != null) {
                        httpPost.setEntity(new ByteArrayEntity(signatureRequest.bodyByte, ContentType.create((String) signatureRequest.headers.get("content-type"))));
                    }
                    httpRequest = httpPost;
                    break;
                default:
                    System.out.println("Metode HTTP tidak didukung: " + signatureRequest.httpMethod);
                    throw new IllegalArgumentException("Metode HTTP tidak didukung");
            }
            try (CloseableHttpClient httpClient = HttpClients.createDefault(); CloseableHttpResponse response = httpClient.execute(httpRequest)) {
                String result = EntityUtils.toString(response.getEntity(), StandardCharsets.UTF_8);
                System.out.println(result);
            } catch (IOException e) {
                System.out.println("Gagal mengirim permintaan");
                throw new RuntimeException(e);
            }
        } catch (URISyntaxException e) {
            throw new RuntimeException(e);
        }
    }

    private static String formDataToString(Map<String, Object> formData) {
        Map<String, Object> tileMap = new HashMap<>();
        processObject(tileMap, "", formData);
        StringBuilder result = new StringBuilder();
        boolean first = true;
        String symbol = "&";
        for (Map.Entry<String, Object> entry : tileMap.entrySet()) {
            String value = String.valueOf(entry.getValue());
            if (value != null && !value.isEmpty()) {
                if (first) {
                    first = false;
                } else {
                    result.append(symbol);
                }
                result.append(percentEncode(entry.getKey()));
                result.append("=");
                result.append(percentEncode(value));
            }
        }

        return result.toString();
    }

    private static void processObject(Map<String, Object> map, String key, Object value) {
        // Tidak diperlukan pemrosesan lebih lanjut untuk nilai null.
        if (value == null) {
            return;
        }
        if (key == null) {
            key = "";
        }
        // Jika nilai bertipe List, telusuri daftar dan lakukan rekursi pada setiap elemen.
        if (value instanceof List<?>) {
            List<?> list = (List<?>) value;
            for (int i = 0; i < list.size(); ++i) {
                processObject(map, key + "." + (i + 1), list.get(i));
            }
        } else if (value instanceof Map<?, ?>) {
            // Jika nilai bertipe Map, telusuri peta dan lakukan rekursi pada setiap pasangan kunci-nilai.
            Map<?, ?> subMap = (Map<?, ?>) value;
            for (Map.Entry<?, ?> entry : subMap.entrySet()) {
                processObject(map, key + "." + entry.getKey().toString(), entry.getValue());
            }
        } else {
            // Jika kunci diawali dengan titik (.), hapus titik (.) tersebut agar kunci tetap berkesinambungan.
            if (key.startsWith(".")) {
                key = key.substring(1);
            }
            // Jika nilai berformat byte[], konversi nilai tersebut menjadi string yang dienkod dalam UTF-8.
            if (value instanceof byte[]) {
                map.put(key, new String((byte[]) value, StandardCharsets.UTF_8));
            } else {
                // Konversi nilai tipe lain menjadi string.
                map.put(key, String.valueOf(value));
            }
        }
    }

    public static String generateSignature(String accessSecret, String stringToSign) {
        try {
            // Buat kunci HMAC-SHA1.
            SecretKeySpec signingKey = new SecretKeySpec((accessSecret + "&").getBytes(StandardCharsets.UTF_8), "HmacSHA1");
            // Buat dan inisialisasi instance Mac
            Mac mac = Mac.getInstance("HmacSHA1");
            mac.init(signingKey);
            // Hitung string tanda tangan menggunakan algoritma HMAC-SHA1.
            byte[] rawHmac = mac.doFinal(stringToSign.getBytes(StandardCharsets.UTF_8));
            return Base64.getEncoder().encodeToString(rawHmac);
        } catch (NoSuchAlgorithmException | InvalidKeyException e) {
            System.out.println("Gagal menghasilkan tanda tangan HMAC-SHA1");
            throw new RuntimeException(e);
        }
    }

    public static String percentEncode(String str) {
        if (str == null) {
            throw new IllegalArgumentException("String yang ditentukan tidak boleh null.");
        }
        try {
            return URLEncoder.encode(str, StandardCharsets.UTF_8.name()).replace("+", "%20").replace("*", "%2A").replace("%7E", "~");
        } catch (UnsupportedEncodingException e) {
            throw new RuntimeException("Enkode UTF-8 tidak didukung.", e);
        }
    }
}

Contoh Python

Untuk menjalankan kode contoh, instal library requests:

pip install requests

import base64
import hashlib
import hmac
import os
import urllib.parse
import uuid
from collections import OrderedDict
from datetime import datetime, UTC
from typing import Dict, Any

import requests

# Dapatkan pasangan AccessKey dari variabel lingkungan.
ACCESS_KEY_ID = os.environ.get("ALIBABA_CLOUD_ACCESS_KEY_ID")
ACCESS_KEY_SECRET = os.environ.get("ALIBABA_CLOUD_ACCESS_KEY_SECRET")


class SignatureRequest:
    """
    Kelas untuk menandatangani permintaan. Kelas ini digunakan untuk membangun dan mengelola permintaan API RPC.
    """

    def __init__(self, http_method: str, host: str, action: str, version: str):
        """
        Inisialisasi objek permintaan tanda tangan.

        Args:
            http_method: Metode permintaan HTTP, seperti GET atau POST.
            host: Nama domain layanan API.
            action: Nama aksi API.
            version: Nomor versi API.
        """
        self.http_method = http_method.upper()
        self.host = host
        self.action = action
        self.version = version
        self.canonical_uri = "/"  # API RPC menggunakan path root.
        self.headers: Dict[str, Any] = OrderedDict()  # Parameter header permintaan.
        self.query_params: Dict[str, Any] = OrderedDict()  # Parameter kueri.
        self.body: Dict[str, Any] = OrderedDict()  # Parameter badan permintaan.
        self.body_byte: bytes = b""  # Badan permintaan dalam bentuk byte.
        self.all_params: Dict[str, Any] = OrderedDict()  # Kumpulan semua parameter.
        self.set_headers()

    def set_headers(self) -> None:
        """
        Menetapkan parameter header permintaan dasar yang diperlukan untuk permintaan RPC.
        """
        self.headers["AccessKeyId"] = ACCESS_KEY_ID  # ID AccessKey.
        self.headers["Format"] = "JSON"  # Format tanggapan.
        self.headers["SignatureMethod"] = "HMAC-SHA1"  # Algoritma tanda tangan.
        self.headers["SignatureVersion"] = "1.0"  # Versi tanda tangan.
        self.headers["SignatureNonce"] = "{" + str(uuid.uuid4()) + "}"  # String acak untuk anti-replay.
        self.headers["Timestamp"] = datetime.now(UTC).strftime("%Y-%m-%dT%H:%M:%SZ")  # Cap waktu.
        self.headers["Action"] = self.action  # Nama API.
        self.headers["Version"] = self.version  # Nomor versi API.

    def set_content_type(self, content_type):
        self.headers["Content-Type"] = content_type

    def get_all_params(self) -> None:
        """
        Mengumpulkan dan mengurutkan semua parameter permintaan.
        """
        # Gabungkan semua parameter: headers, query_params, dan body.
        self.all_params.update(self.headers)
        if self.query_params:
            self.all_params.update(self.query_params)
        if self.body:
            self.body_byte = form_data_to_string(body).encode("utf-8")
            self.all_params.update(self.body)

        # Urutkan parameter berdasarkan nama dalam urutan ASCII.
        self.all_params = OrderedDict(sorted(self.all_params.items()))


def calculate_signature(signature_request: SignatureRequest) -> None:
    """
    Menghitung tanda tangan untuk permintaan RPC.

    Args:
        signature_request: Objek permintaan tanda tangan.
    """
    signature_request.get_all_params()  # Kumpulkan dan urutkan semua parameter.

    # Bangun string kueri yang dinormalisasi.
    canonical_query_string = "&".join(
        f"{percent_encode(k)}={percent_encode(v)}"
        for k, v in signature_request.all_params.items()
    )
    print(f"canonicalQueryString:{canonical_query_string}")

    # Bangun string yang akan ditandatangani: metode HTTP + URI kanonis + string kueri kanonis.
    string_to_sign = (
        f"{signature_request.http_method}&"
        f"{percent_encode(signature_request.canonical_uri)}&"
        f"{percent_encode(canonical_query_string)}"
    )
    print(f"stringToSign:{string_to_sign}")

    # Hasilkan tanda tangan.
    signature = generate_signature(ACCESS_KEY_SECRET, string_to_sign)
    signature_request.all_params["Signature"] = signature  # Tambahkan tanda tangan ke parameter.


def form_data_to_string(form_data: Dict[str, Any]) -> str:
    """
    Mengonversi data formulir menjadi string yang dienkod URL.

    Args:
        form_data: Kamus data formulir.

    Returns:
        String yang dienkod URL.
    """
    tile_map: Dict[str, Any] = {}

    def process_object(key: str, value: Any) -> None:
        """
        Memproses objek secara rekursif untuk meratakan struktur bersarangnya.

        Args:
            key: Kunci parameter.
            value: Nilai parameter.
        """
        if value is None:
            return
        if isinstance(value, list):
            # Proses parameter bertipe daftar.
            for i, item in enumerate(value):
                process_object(f"{key}.{i + 1}", item)
        elif isinstance(value, dict):
            # Proses parameter bertipe kamus.
            for k, v in value.items():
                process_object(f"{key}.{k}", v)
        else:
            # Hapus titik awal.
            clean_key = key[1:] if key.startswith(".") else key
            # Proses data byte dan data biasa.
            tile_map[clean_key] = value.decode("utf-8") if isinstance(value, bytes) else str(value)

    # Proses semua data formulir.
    for k, v in form_data.items():
        process_object(k, v)

    # Enkode URL dan gabungkan item.
    encoded_items = [
        f"{percent_encode(k)}={percent_encode(v)}"
        for k, v in tile_map.items() if v
    ]

    return "&".join(encoded_items)


def generate_signature(access_secret: str, string_to_sign: str) -> str:
    """
    Menghasilkan tanda tangan menggunakan algoritma HMAC-SHA1.

    Args:
        access_secret: Rahasia AccessKey.
        string_to_sign: String yang akan ditandatangani.

    Returns:
        Tanda tangan yang dienkod Base64.
    """
    try:
        # Kunci penandatanganan adalah rahasia AccessKey yang ditambahkan dengan tanda ampersand (&).
        signing_key = (access_secret + "&").encode("utf-8")
        # Hitung tanda tangan menggunakan algoritma HMAC-SHA1.
        signature = hmac.new(signing_key, string_to_sign.encode("utf-8"), hashlib.sha1).digest()
        # Enkode tanda tangan dalam Base64.
        return base64.b64encode(signature).decode("utf-8")
    except Exception as e:
        print(f"Gagal menghasilkan tanda tangan HMAC-SHA1: {e}")
        raise


def percent_encode(s: str) -> str:
    """
    Melakukan enkode persen pada string berdasarkan RFC 3986.

    Args:
        s: String yang akan dienkod.

    Returns:
        String yang telah dienkod.
    """
    if s is None:
        raise ValueError("String input tidak boleh None")
    # Enkode URL string setelah enkode UTF-8. Karakter tilde (~) tidak dienkod.
    encoded = urllib.parse.quote(s.encode("utf-8"), safe=b"~")
    # Ganti enkode karakter khusus.
    return encoded.replace("+", "%20").replace("*", "%2A")


def call_api(signature_request: SignatureRequest) -> None:
    """
    Contoh cara memulai permintaan API.
    """
    url = f"https://{signature_request.host}/"

    # Susun parameter permintaan.
    params = {k: str(v) for k, v in signature_request.all_params.items()}

    # Siapkan parameter permintaan.
    request_kwargs = {
        "params": params
    }

    # Tambahkan data badan permintaan jika ada.
    if signature_request.body_byte:
        request_kwargs["data"] = signature_request.body_byte
        headers = {"Content-Type": signature_request.headers.get("Content-Type")}
        request_kwargs["headers"] = headers

    try:
        # Gunakan requests.request untuk menangani berbagai metode HTTP.
        response = requests.request(
            method=signature_request.http_method,
            url=url,
            **request_kwargs
        )

        print(f"URL Permintaan: {response.url}")
        print(f"Tanggapan: {response.text}")

    except requests.RequestException as e:
        print(f"Permintaan HTTP gagal: {e}")
        raise
    except Exception as e:
        print(f"Gagal mengirim permintaan: {e}")
        raise


if __name__ == "__main__":
    # Contoh 1: Permintaan tanpa badan. Header Content-Type opsional. Jika Anda menentukan header ini, tetapkan nilainya ke application/json.
    signature_request = SignatureRequest(
        http_method="POST",
        host="dysmsapi.aliyuncs.com",
        action="SendSms",
        version="2017-05-25"
    )
    # Gunakan query_params untuk mengonfigurasi parameter kueri.
    signature_request.query_params["SignName"] = "******"
    signature_request.query_params["TemplateCode"] = "SMS_******"
    signature_request.query_params["PhoneNumbers"] = "******"
    signature_request.query_params["TemplateParam"] = "{'code':'1234'}"

    # Contoh 2: Permintaan dengan badan. Header Content-Type harus diatur ke application/x-www-form-urlencoded. Jangan atur ke application/json.
    """
    signature_request = SignatureRequest(
        http_method="POST",
        host="mt.aliyuncs.com",
        action="TranslateGeneral",
        version="2018-10-12"
    )
    body = {
        "FormatType": "text",
        "SourceLanguage": "zh",
        "TargetLanguage": "en",
        "SourceText": "Hello",
        "Scene": "general"
    }
    signature_request.body = body
    signature_request.set_content_type("application/x-www-form-urlencoded")
    """

    # Contoh 3: Unggah aliran file biner. Header Content-Type harus diatur ke application/octet-stream.
    """
    signature_request = SignatureRequest(
        http_method="POST",
        host="ocr-api.cn-hangzhou.aliyuncs.com",
        action="RecognizeGeneral",
        version="2021-07-07"
    )
    with open("D:\\test.jpeg", "rb") as f:
        signature_request.body_byte = f.read()
    signature_request.set_content_type("application/octet-stream")
    """

    # Hitung tanda tangan.
    calculate_signature(signature_request)

    # Mulai permintaan contoh.
    call_api(signature_request)