インターフェイスの呼び出し方法 - - Alibaba Cloud ドキュメントセンター

ECS サービスインターフェイスの呼び出しは、HTTP リクエストを ECS サーバーに (HTTP または HTTPS チャネルを介して) 送信し、このリクエストに対する ECS サーバーの応答を受信することで行われます。ECS サーバーはユーザーリクエストを受信した後に、そのリクエストに対して必要な認証とパラメーターの検証を実行します。すべての検証で問題がなければ、そのリクエスト用に指定されたパラメーターに基づき、関連する操作が送信または実行されます。その後、処理結果が HTTP 応答として呼び出し元に返されます。

リクエストは以下の部分で構成されます。

HTTP メソッド - 現在、どの ECS サービスインターフェイスも GET メソッドによる呼び出しのみをサポートしています。

リクエスト URL - リクエスト URL には、リクエストのサービスアドレス、実行する操作名、操作パラメーター、パブリックリクエストパラメーターが含まれます。

サーバーアドレス: ECS サービスドメイン名は http://ecs.aliyuncs.com/ と https://ecs.aliyuncs.com/ です。リクエストのセキュリティを確保するために、HTTPS チャネルの使用を強くお勧めします (HTTPS は暗号化通信用の SSL 層を備えており、機密情報の漏洩につながる通信の傍受を防止できます)。

操作名: 各インターフェイスに、実行する操作の名前を Action パラメーターとして指定する必要があります。

操作パラメーター: 実行する操作に応じて、個別の操作パラメーターを設定する必要があります。詳細については、各インターフェイスについての説明を参照してください。

パブリックリクエストパラメーター: TimeStamp や Signature などのパラメーターを各リクエストに含める必要があります。

サーバーでユーザーの ID を正確に認証し、リクエストの実行を許可するには、処理の送信に先立って、リクエストに署名する必要があります。署名ルールについては、「署名メカニズム」のセクションを参照してください。

サーバーはリクエストの処理を完了した後、応答結果を返します。応答結果は、正常な結果かエラーメッセージのいずれかに分類されます。結果の形式については、「返される結果」のセクションをご確認ください。クライアントは応答メッセージの本文を解析し、実行結果を取得することができます。

呼び出しの例

DescribeRegions インターフェイスを例にとります。

対応する Action は DescribeRegions で、必要な操作パラメーターは RegionId です (ECS では、必要なリージョンリストを照会するためのインターフェイスを使用して、すべての RegionId を取得できます)。すべてのパブリックリクエストパラメーター (Signature を除く) を追加した後のリクエスト URL は次のようになります (見やすくするために、URL エンコーディング前の URL を記載しています)。

http://ecs.aliyuncs.com/?TimeStamp=2012-12-26T10:33:56Z&Format=XML&AccessKeyId=testid&Action=DescribeRegions&SignatureMethod=HMAC-SHA1&SignatureNonce=NwDAxvLU6tFE0DVb&Version=2014-05-26&SignatureVersion=1.0

まず、署名計算ルールに従って、正規化クエリ文字列を作成します。

http://ecs.aliyuncs.com/?TimeStamp=2012-12-26T10:33:56Z&Format=XML&AccessKeyId=testid&Action=DescribeRegions&SignatureMethod=HMAC-SHA1&SignatureNonce=NwDAxvLU6tFE0DVb&Version=2014-05-26&SignatureVersion=1.0

続いて、特定の値を持つ署名文字列 StringToSign を作成します。

GET&%2F&AccessKeyId%3Dtestid&Action%3DDescribeRegions&Format%3DXML&SignatureMethod%3DHMAC-SHA1&SignatureNonce%3DNwDAxvLU6tFE0DVb&SignatureVersion%3D1.0&TimeStamp%3D2012-12-26T10%253A33%253A56Z&Version%3D2014-05-26

以下の Java サンプルコードでは、パブリックリクエストパラメーターを追加する方法、リクエストパラメーターから正規化クエリ文字列を作成する方法、StringToSign を作成する方法を示しています。この例では前提として、すべてのリクエストパラメーターが Map<String, String> オブジェクトに格納されること、および Access Key ID が testid であることを想定しています。

    final String HTTP_METHOD = "GET";

    Map<String, String> parameters = new HashMap<String, String>();
    // Add public request parameters
    parameters.put("Action", "DescribeRegions");
    parameters.put("Version", "2014-05-26");
    parameters.put("AccessKeyId", "testid");
    parameters.put("TimeStamp", formatIso8601Date(new Date()));
    parameters.put("SignatureMethod", "HMAC-SHA1");
    parameters.put("SignatureVersion", "1");
    parameters.put("SignatureNonce", UUID.randomUUID().toString());
    parameters.put("Format", "XML");

    // Sort the parameters
    String[] sortedKeys = parameters.keySet().toArray(new String[]{});
    Arrays.sort(sortedKeys);

    final String SEPARATOR = "&";

    // Generate the stringToSign
    StringBuilder stringToSign = new StringBuilder();
    stringToSign.append(HTTP_METHOD).append(SEPARATOR);
    stringToSign.append(percentEncode("/")).append(SEPARATOR);

    StringBuilder canonicalizedQueryString = new StringBuilder();
    for(String key : sortedKeys) {
        // Be sure to encode the key and value
        canonicalizedQueryString.append("&")
        .append(percentEncode(key)).append("=")
        .append(percentEncode(parameters.get(key)));
    }

    // Be sure to encode the canonicalizedQueryString
    stringToSign.append(percentEncode(
        canonicalizedQueryString.toString().substring(1)));

この例では、TimeStamp パラメーターが ISO8601 標準に準拠する必要があることに注意してください。さらに、UTC 時刻が用いられていることにも留意します。これらを満たさないと、リクエストはエラーになります。次のサンプルコードは、標準に準拠した TimeStamp 文字列の生成方法を示します。

    private static final String ISO8601_DATE_FORMAT = "yyyy-MM-dd'T'HH:mm:ss'Z'";
    private static String formatIso8601Date(Date date) {
        SimpleDateFormat df = new SimpleDateFormat(ISO8601_DATE_FORMAT);
        df.setTimeZone(new SimpleTimeZone(0, "GMT"));
        return df.format(date);
    }

正規化クエリ文字列 (この例では canonicalizedQueryString 変数) と StringToSign を生成する際に、これらの両方をエンコードする必要があります。エンコーディングルールについては、「署名メカニズム」のセクションで詳述しています。次のサンプルコードは、java.net.URLEncoder クラスを使用してエンコーディングを実行する方法を示します。

    private static final String ENCODING = "UTF-8";

    private static String percentEncode(String value) throws UnsupportedEncodingException {
        return value != null ? URLEncoder.encode(value, ENCODING).replace("+", "%20").replace("*", "%2A").replace("%7E", "~") : null;
    }

“Access Key ID” を “testid”、”Access Key Secret” を “testsecret”、HMAC の計算に使用する Key を “testsecret&” とすると、次の署名値が計算されます。

            SDFQNvyH5rtkc9T5Fwo8DOjw5hc=

署名を計算するサンプルコード (Java) を以下に示します。

    // The following is a sample code for signature calculation
    final String ALGORITHM = "HmacSHA1";
    final String ENCODING = "UTF-8";
    key = "testsecret&";

    Mac mac = Mac.getInstance(ALGORITHM);
    mac.init(new SecretKeySpec(key.getBytes(ENCODING), ALGORITHM));
    byte[] signData = mac.doFinal(stringToSign.getBytes(ENCODING));

    String signature = new String(Base64.encodeBase64(signData));

Signature パラメーターを追加した後、RFC3986 ルールに従って URL エンコーディングを実行すると、次のような結果が得られます。

http://ecs.aliyuncs.com/?TimeStamp=2012-12-26T10%3A33%3A56Z&Format=XML&AccessKeyId=testid&Action=DescribeRegions&SignatureMethod=HMAC-SHA1&RegionId=region1&SignatureNonce=NwDAxvLU6tFE0DVb&Version=2012-09-13&SignatureVersion=1.0&Signature=SDFQNvyH5rtkc9T5Fwo8DOjw5hc%3d

次に HTTP リクエストを上記の URL に送信し、次のようなリクエストに対する ECS サーバーの応答を受信します。

<DescribeRegionsResponse>
    <Regions>
        <Region>
            <LocalName>Qingdao node</LocalName>
            <RegionId>cn-qingdao</RegionId>
        </Region>
        <Region>
            <LocalName>Hangzhou node</LocalName>
            <RegionId>cn-hangzhou</RegionId>
        </Region>
    </Regions>
    <RequestId>833C6B2C-E309-45D4-A5C3-03A7A7A48ACF</RequestId>
</DescribeRegionsResponse>

この XML 出力を解析して、すべての利用可能なリージョンに関する ID と LocalName のリストを取得することができます。リクエストの送信時に Format パラメーターとして JSON を指定した場合は、結果も JSON 形式で返されます。