tencent cloud

TencentCloud API

ドキュメントTencentCloud API開発ガイドGO API

GO API

Download
フォーカスモード
フォントサイズ
最終更新日: 2026-01-23 11:39:51
TencentCloud APIは完全にアップグレードされたバージョン3.0です。このバージョンでは、パフォーマンスが最適化され、全リージョンにデプロイされ、近接アクセスとリージョン別アクセスをサポートし、アクセスレイテンシが顕著に低下しました。APIの説明がより詳細になり、エラーコードの説明がより包括的になり、SDKにAPIレベルのコメントが追加され、Tencent Cloud製品をより便利かつ迅速に利用できます。ここでは、GO APIの呼び出し方法について簡単に説明します。 現在、クラウドサーバー（CVM）、クラウドディスク（CBS）、プライベートネットワーク（VPC）、クラウドデータベース（TencentDB）などのTencent Cloud製品をサポートしています。今後、他のクラウド製品のアクセスもサポートする予定です。期待してください。

リクエスト構造を理解する

1. サービスアドレス（endpoint）

APIは近接リージョンアクセス（例：cvm製品ドメインはcvm.tencentcloudapi.com）をサポートしており、指定リージョンドメインアクセス（例：広州地域のドメインはcvm.ap-guangzhou.tencentcloudapi.com）もサポートしています。各リージョンのパラメータについては、共通パラメータのリージョンリストを参照してください。詳細は各製品の「リクエスト構造」ドキュメントで当該リージョンのサポート状況を確認してください。
注意：
レイテンシの影響を受けやすい業務には、リージョン付きのドメインの指定を推奨されます。

2. 通信プロトコル

TencentCloud APIのすべてのインターフェースはHTTPSを介して通信を行い、高セキュリティの通信チャネルを提供します。

3. リクエスト方法

サポートされている HTTP リクエスト方法：
POST（推奨）
GET
POSTリクエストがサポートするContent-Typeの種類：
application/json（推奨）、署名方式 v3（TC3-HMAC-SHA256）を使用する必要があります。
application/x-www-form-urlencoded の場合、署名方式 v1（HmacSHA1 または HmacSHA256）を使用する必要があります。
multipart/form-data（一部のAPIのみサポートされています）、署名方式 v3（TC3-HMAC-SHA256）を使用する必要があります。
GETリクエストのリクエストパッケージサイズは32KBを超えてはなりません。POSTリクエストで署名方式v1（HmacSHA1、HmacSHA256）を使用する場合、1MBを超えてはなりません。POSTリクエストで署名方式v3（TC3-HMAC-SHA256）を使用する場合、10MBをサポートします。

4. 文字エンコーディング

いずれもUTF-8エンコーディングを使用しています。

共通パラメータ

説明：
共通パラメータはユーザーとAPI署名を識別するためのパラメータであり、正常にリクエストを開始するには、リクエストごとにこれらのパラメータを含める必要があります。

署名方法 V3 共通パラメータ

署名方式 v3（時には TC3-HMAC-SHA256 とも呼ばれる）は、署名方式 v1（一部のドキュメントでは「署名方式」と略称される場合があります）と比較して、より安全で、より大きなリクエストパッケージをサポートし、POST JSON 形式をサポートし、パフォーマンスが一定向上しています。この署名方式を使用して署名を計算することを推奨します。使用方法については、以下の「署名方式の紹介」を参照してください。
パラメータ名
タイプ
必須
説明
X-TC-Action
String
はい
操作のAPI名。値はAPIドキュメントの入力パラメータの共通パラメータActionの説明を参照してください。例えばCVMのインスタンスリスト検索APIは、値がDescribeInstancesです。
X-TC-Region
String
-
リージョンパラメータは、操作対象となるデータのリージョンを識別するために使用されます。APIが受け入れるリージョンの値については、APIドキュメントの入力パラメータの共通パラメータRegionの説明を参照してください。注意：一部のAPIではこのパラメータの受け渡しが不要であり、APIドキュメントに特別な記載があります。その場合、パラメータを渡しても有効になりません。
X-TC-Timestamp
Integer
はい
現在のUNIXタイムスタンプは、APIリクエストを開始した時間を記録できます。例えば、1529223702。注意：サーバー時間と5分以上の差がある場合、署名の期限切れエラーが発生します。
X-TC-Version
String
はい
操作するAPIのバージョン。値をAPIドキュメントの入力パラメータの共通パラメータVersionの説明を参照してください。例えばCVMのバージョン2017-03-12です。
Authorization
String
はい
HTTP標準認証ヘッダーフィールド。例：TC3-HMAC-SHA256 Credential=AKIDEXAMPLE/Date/service/tc3_request, SignedHeaders=content-type;host, Signature=72e494ea8******************************************a96525168
ここで：
TC3-HMAC-SHA256：署名方式であり、現在はこの値に固定されています。
Credential：署名の認証情報。AKIDEXAMPLEはSecretIdです。
DateはUTC標準時の日付であり、その値は共通パラメータX-TC-Timestampを変換したUTC標準時の日付と一致する必要があります。
serviceは製品名であり、通常はドメインのプレフィックスです。例えば、ドメイン cvm.tencentcloudapi.com は製品名が cvm であることを意味します。本製品の値は cvm です。
SignedHeaders：署名計算に参加するヘッダー情報であり、content-type と host は必須ヘッダーです。
Signature：署名ダイジェスト。計算プロセスの詳細は下記を参照してください。
X-TC-Token
String
いいえ
一時的な証明書で使用されるTokenは、一時的なシークレットキーと組み合わせて使用する必要があります。一時的なシークレットキーとTokenは、CAMサービスでAPIを呼び出して取得する必要があります。長期シークレットキーにはTokenは不要です。

署名方式 V1 共通パラメータ

署名方式v1（時には HmacSHA256 や HmacSHA1 と呼ばれることもあります）を使用する場合、共通パラメータはリクエスト文字列に統一して配置する必要があります。
パラメータ名
タイプ
必須
説明
Action
String
はい
操作するAPI名。値はAPIドキュメントの入力パラメータの共通パラメータActionの説明を参照してください。例えばCVMのインスタンスリストの表示APIの場合、値はDescribeInstancesです。
Region
String
-
リージョンパラメータは、操作対象となるデータのリージョンを識別するために使用されます。APIが受け入れるリージョンの値については、APIドキュメントの入力パラメータの共通パラメータRegionの説明を参照してください。注意：一部のAPIではこのパラメータの受け渡しが不要であり、APIドキュメントに特別な記載があります。その場合、パラメータを渡しても有効になりません。
Timestamp
Integer
はい
現在のUNIXタイムスタンプは、APIリクエストを開始した時間を記録できます。例えば、1529223702。現在の時間と差が大きすぎる場合、署名の期限切れエラーが発生します。
Nonce
Integer
はい
ランダムな正の整数であり、Timestampと組み合わせてリプレイ攻撃を防止するために使用されます。
SecretId
String
はい
TencentCloud APIキーで申請されたIDを識別するSecretIdであり、一つのSecretIdは唯一のSecretKeyに対応します。SecretKeyはリクエストの署名Signatureを生成するために使用されます。
Signature
String
はい
リクエスト署名は、今回のリクエストの正当性を検証するために使用されます。ユーザーは実際の入力パラメータに基づいて計算する必要があります。具体的な計算方法については、下記の「署名方法の紹介」を参照してください。
Version
String
はい
操作するAPIのバージョン。値をAPIドキュメントの入力パラメータの共通パラメータVersionの説明を参照してください。例えばCVMのバージョン2017-03-12です。
SignatureMethod
String
いいえ
署名方式は、現在HmacSHA256とHmacSHA1をサポートしています。このパラメータをHmacSHA256に指定した場合のみ、HmacSHA256アルゴリズムを使用して署名を検証します。その他の場合はすべてHmacSHA1を使用して署名を検証します。
Token
String
いいえ
一時的な証明書で使用されるTokenは、一時的なシークレットキーと組み合わせて使用する必要があります。一時的なシークレットキーとTokenは、CAMサービスでAPIを呼び出して取得する必要があります。長期シークレットキーにはTokenは不要です。

リージョン一覧

各製品がサポートするリージョンは異なるため、詳細は各製品のドキュメントにあるリージョンリストを参照してください。 例えば、CVMのリージョンリストを参照できます。

GO APIの呼び出し方法

TencentCloud APIは各リクエストに対して認証を行います。ユーザーはセキュリティ認証情報を使用し、特定の手順を経てリクエストに署名（Signature）を実行する必要があります。各リクエストには、共通リクエストパラメータでこの署名結果を指定し、指定された方式と形式で送信する必要があります。
ユーザーのSecretIdとSecretKeyがそれぞれ：AKIDz8krbsJ5**********mLPx3EXAMPLE と Gu5t9xGAR***********EXAMPLEであると仮定します。ユーザーが広州リージョンのCVMで「未命名」という名前のホストステータスを確認したい場合、データを1件のみ返します。リクエストは次のようになります： 
curl -X POST https://cvm.tencentcloudapi.com \\
-H "Authorization: TC3-HMAC-SHA256 Credential=AKIDz8krbsJ5**********mLPx3EXAMPLE/2019-02-25/cvm/tc3_request, SignedHeaders=content-type;host, Signature=72e494ea8******************************************a96525168" \\
-H "Content-Type: application/json; charset=utf-8" \\
-H "Host: cvm.tencentcloudapi.com" \\
-H "X-TC-Action: DescribeInstances" \\
-H "X-TC-Timestamp: 1551113065" \\
-H "X-TC-Version: 2017-03-12" \\
-H "X-TC-Region: ap-guangzhou" \\
-d '{"Limit": 1, "Filters": [{"Values": ["\\u672a\\u547d\\u540d"], "Name": "instance-name"}]}'

ステップ1：セキュリティ認証情報を申請する

このドキュメントで使用されるセキュリティ認証情報はシークレットキーです。シークレットキーはSecretIdとSecretKeyを含みます。各ユーザーは最大で2つのキーペアを所有できます。
SecretId：API呼び出し元の身分を識別するために使用され、ユーザー名に簡単に例えることができます。
SecretKey：API呼び出し元の身分を認証するために使用され、パスワードに簡単に例えることができます。
注意：
ユーザーはセキュリティ認証情報を厳重に保管し、漏洩を防止する必要があります。さもなければ、財産の安全が危険にさらされます。万が一漏洩した場合は、直ちにそのセキュリティ認証情報を無効にしてください。
APIキー管理 ページに移動すると、取得できます。下図の通りです：




ステップ2：

1. API 3.0 V3 バージョンのシグネチャを取得する

署名方式 v3 (TC3-HMAC-SHA256) は、以前の署名方式 v1 を機能的にカバーしており、より安全で、より大きなリクエストをサポートし、json形式をサポートし、パフォーマンスが向上しています。この署名方式を使用して署名を計算することを推奨します。


注意：
初めて使用する場合は、API Explorerの「署名文字列生成」機能を使用し、署名バージョンに「API 3.0 署名 v3」を選択することが推奨されます。これにより署名プロセスを生成して検証できるほか、直接的にSDKコードを生成することも可能です。Tencent Cloud API対応の7種類の主要プログラミング言語向けSDKの使用を推奨します。これらは署名とリクエストプロセスをカプセル化し、すべてオープンソース化されており、Python、Java、PHP、Go、NodeJS、.NET、C++をサポートしています。
TencentCloud APIはGETおよびPOSTリクエストをサポートします。GETメソッドの場合、Content-Type: application/x-www-form-urlencodedプロトコル形式のみサポートします。POSTメソッドの場合、現在Content-Type: application/jsonおよびContent-Type: multipart/form-dataの2種類のプロトコル形式をサポートしており、json形式はほとんどのAPIでサポートされますが、multipart形式は特定のAPIのみでサポートされます。この場合、当該APIはjson形式で呼び出すことができません。具体的な業務APIのドキュメント説明を参照してください。両者の結果に差異はありませんが、GETリクエストは32KB以内のリクエストパケットのみサポートするため、POSTリクエストの使用を推奨します。
以下はインスタンスリストの表示APIを例として、署名の計算プロセスをステップごとに説明します。このAPIを選択した理由は：
1. CVMはデフォルトで有効化されており、このAPIはよく使用されます。
2. このAPIは読み取り専用であり、既存リソースの状態を変更しません。
3. APIはカバーするパラメータの種類が比較的完全であり、データ構造を含む配列の使用方法をデモンストレーションできます。

1. 正規リクエスト文字列を連結する

CanonicalRequest =
    HTTPRequestMethod + '\\n' +
    CanonicalURI + '\\n' +
    CanonicalQueryString + '\\n' +
    CanonicalHeaders + '\\n' +
    SignedHeaders + '\\n' +
    HashedRequestPayload
フィールド名称
説明
HTTPRequestMethod
HTTPリクエスト方法（GET、POST）。このサンプルでは、値はPOSTです。
CanonicalURI
URIパラメータは、API 3.0ではスラッシュ（/）に固定されます。
CanonicalQueryString
HTTPリクエストURLのクエリ文字列です。POSTリクエストの場合、空文字列""に固定されます。GETリクエストの場合、URL内の疑問符（?）以降の文字列内容となります（例：Limit=10&Offset=0）。注意：CanonicalQueryStringはRFC3986を参照してURLEncodeを行う必要があり、文字セットはUTF8です。プログラミング言語の標準ライブラリを使用することを推奨し、すべての特殊文字をエンコードし、大文字形式とします。
CanonicalHeaders
署名に使用するヘッダー情報は、少なくともhostとcontent-typeの2つのヘッダーを含める必要があります。また、カスタムヘッダーを追加して署名に参加させることで、リクエストの一意性と安全性を高めることができます。 連結ルール：ヘッダーのkeyとvalueはすべて小文字に変換し、先頭と末尾のスペースを削除した後、key:value\\n の形式で連結します。複数のヘッダーがある場合は、ヘッダーのkey（小文字）のASCIIコードの昇順で連結します。 この例での計算結果はcontent-type:application/json; charset=utf-8\\nhost:cvm.tencentcloudapi.com\\nです。 注意：content-typeは実際に送信するものと一致している必要があります。一部のプログラミング言語のネットワークライブラリは、指定されていない場合でも自動的にcharset値を追加することがあります。署名時と送信時でcontent-typeが一致しない場合、サーバーは署名検証失敗を返します。
SignedHeaders
署名に参加するヘッダー情報であり、今回のリクエストでどのヘッダーが署名に参加したかを説明します。CanonicalHeadersに含まれるヘッダー内容と一対一対応します。content-typeとhostは必須ヘッダーです。 連結ルール：ヘッダーのkeyはすべて小文字に変換します。複数のヘッダーkey（小文字）はASCII昇順で連結し、セミコロン（;）で区切ります。この例では、content-type;hostとなります。
HashedRequestPayload
リクエスト本文（Requestpayload、すなわちbodyです。この例では{"Limit": 1, "Filters": [{"Values": ["\\u672a\\u547d\\u540d"], "Name": "instance-name"}]}）のハッシュ値です。計算の疑似コードは Lowercase(HexEncode(Hash.SHA256(RequestPayload))) であり、HTTPリクエスト本文に対してSHA256ハッシュを適用し、16進数エンコードした後、エンコード文字列を小文字に変換します。GETリクエストの場合、RequestPayloadは空文字列に固定されます。この例の計算結果は35e9c5b0e3ae67532d3c9f17ead6c90222632e5b1ff7f6e89887f1398934f064です。
以上のルールに基づき、サンプルで得られる正規リクエスト文字列は以下の通りです： 
POST
/

content-type:application/json; charset=utf-8
host:cvm.tencentcloudapi.com

content-type;host
35e9c5b0e3ae67532d3c9f17ead6c90222632e5b1ff7f6e89887f1398934f064

2. 署名対象文字列を組み立てる

以下の形式で署名対象文字列を連結します：
StringToSign =
    Algorithm + \\n +
    RequestTimestamp + \\n +
    CredentialScope + \\n +
    HashedCanonicalRequest
フィールド名称
説明
Algorithm
署名アルゴリズムは、現在TC3-HMAC-SHA256に固定されています。
RequestTimestamp
リクエストタイムスタンプは、リクエストヘッダーの共通パラメータX-TC-Timestampの値であり、現在時刻のUNIXタイムスタンプを秒単位で取得したものです。このサンプルの値は 1551113065 です。
CredentialScope
クレデンシャルスコープの形式は Date/service/tc3_request であり、日付、リクエスト対象サービス、終端文字列（tc3_request）を含みます。Date は UTC標準時の日付であり、値は共通パラメータ X-TC-Timestamp から換算した UTC標準時の日付と一致する必要があります、service は製品名であり、呼び出す製品のドメイン名と一致しなければなりません。このサンプルの計算結果は 2019-02-25/cvm/tc3_request です。
HashedCanonicalRequest
前述の手順で連結された正規リクエスト文字列のハッシュ値であり、計算の擬似コードは Lowercase(HexEncode(Hash.SHA256(CanonicalRequest))) です。このサンプルの計算結果は 5ffe6a04c0664d6b969fab9a13bdab201d63ee709638e2749d62a09ca18d7031 です。
注意：
1. DateはタイムスタンプX-TC-Timestampから算出する必要があり、タイムゾーンはUTC+0でなければなりません。システムのローカルタイムゾーン情報（例：UTC+8）を含めると、日中や夜間の呼び出しは成功する可能性がありますが、深夜の時間帯の呼び出しは必ず失敗します。タイムスタンプが1551113065の場合、UTC+8タイムゾーンでは2019-02-26 00:44:25となりますが、算出されるDateはUTC+0の日付であるため2019-02-25となり、2019-02-26ではありません。
2. Timestampは現在のシステム時間である必要があり、システム時間と標準時間が同期していることを確保する必要があります。5分以上の差がある場合は必ず失敗します。長期間にわたって標準時間と同期しない場合、一定期間経過後にリクエストが必ず失敗し、署名の期限切れエラーが返される可能性があります。
以上のルールに基づき、サンプルで得られる署名対象文字列は以下の通りです： 
TC3-HMAC-SHA256
1551113065
2019-02-25/cvm/tc3_request
5ffe6a04c0664d6b969fab9a13bdab201d63ee709638e2749d62a09ca18d7031

3.署名の計算（擬似コード）

secretDate := hmacsha256(date, "TC3"+secretKey)
secretService := hmacsha256(service, secretDate)
secretSigning := hmacsha256("tc3_request", secretService)
signature := hex.EncodeToString([]byte(hmacsha256(string2sign, secretSigning)))
fmt.Println(signature)
派生されたシークレットキー SecretDate、SecretService および SecretSigning はバイナリデータであり、非印字文字を含む可能性があるため、ここでは中間結果を表示しません。
フィールド名称
説明
secretKey
元のsecretKey、すなわちGu5t9xGAR***********EXAMPLE。
date
すなわち、Credential の Date フィールド情報（標準時間）です。このサンプルの値は 2019-02-25 です。
service
すなわちCredentialのServiceフィールドの情報です。この例の値はcvmです。
このサンプルの計算結果は 72e494ea8******************************************a96525168 です。

4. Authorizationの連結

以下の形式でAuthorizationを連結します：
    authorization := fmt.Sprintf("%s Credential=%s/%s, SignedHeaders=%s, Signature=%s",
        algorithm,
        secretId,
        credentialScope,
        signedHeaders,
        signature)
    fmt.Println(authorization)
フィールド名称
説明
algorithm
署名方法はTC3-HMAC-SHA256に固定されています。
secretId
キーペアのSecretId、すなわちAKIDz8krbsJ5**********mLPx3EXAMPLE。
credentialScope
上記参照、クレデンシャルスコープです。このサンプルの計算結果は 2019-02-25/cvm/tc3_request です。
signedHeaders
上記参照、署名に参加するヘッダー情報です。この例の値はcontent-type;hostです。
signature
シグネチャ値。この例の計算結果は72e494ea8******************************************a96525168です。
以上のルールに基づき、サンプルで得られる値は以下の通りです：
TC3-HMAC-SHA256 Credential=AKIDz8krbsJ5**********mLPx3EXAMPLE/2019-02-25/cvm/tc3_request, SignedHeaders=content-type;host, Signature=72e494ea8******************************************a96525168
最終的な完全な呼び出し情報は以下の通りです：
POST https://cvm.tencentcloudapi.com/
Authorization: TC3-HMAC-SHA256 Credential=AKIDz8krbsJ5**********mLPx3EXAMPLE/2019-02-25/cvm/tc3_request, SignedHeaders=content-type;host, Signature=72e494ea8******************************************a96525168
Content-Type: application/json; charset=utf-8
Host: cvm.tencentcloudapi.com
X-TC-Action: DescribeInstances
X-TC-Version: 2017-03-12
X-TC-Timestamp: 1551113065
X-TC-Region: ap-guangzhou

{"Limit": 1, "Filters": [{"Values": ["\\u672a\\u547d\\u540d"], "Name": "instance-name"}]}

5. API 3.0 シグネチャ V3サンプル

package main

import (
    "crypto/hmac"
    "crypto/sha256"
    "encoding/hex"
    "fmt"
    "time"
)

func sha256hex(s string) string {
    b := sha256.Sum256([]byte(s))
    return hex.EncodeToString(b[:])
}

func hmacsha256(s, key string) string {
    hashed := hmac.New(sha256.New, []byte(key))
    hashed.Write([]byte(s))
    return string(hashed.Sum(nil))
}

func main() {
    secretId := "AKIDz8krbsJ5**********mLPx3EXAMPLE"
    secretKey := "Gu5t9xGAR***********EXAMPLE"
    host := "cvm.tencentcloudapi.com"
    algorithm := "TC3-HMAC-SHA256"
    service := "cvm"
    version := "2017-03-12"
    action := "DescribeInstances"
    region := "ap-guangzhou"
    //var timestamp int64 = time.Now().Unix()
    var timestamp int64 = 1551113065

    // step 1: build canonical request string
    httpRequestMethod := "POST"
    canonicalURI := "/"
    canonicalQueryString := ""
    canonicalHeaders := "content-type:application/json; charset=utf-8\\n" + "host:" + host + "\\n"
    signedHeaders := "content-type;host"
    payload := `{"Limit": 1, "Filters": [{"Values": ["\\u672a\\u547d\\u540d"], "Name": "instance-name"}]}`
    hashedRequestPayload := sha256hex(payload)
    canonicalRequest := fmt.Sprintf("%s\\n%s\\n%s\\n%s\\n%s\\n%s",
        httpRequestMethod,
        canonicalURI,
        canonicalQueryString,
        canonicalHeaders,
        signedHeaders,
        hashedRequestPayload)
    fmt.Println(canonicalRequest)

    // step 2: build string to sign
    date := time.Unix(timestamp, 0).UTC().Format("2006-01-02")
    credentialScope := fmt.Sprintf("%s/%s/tc3_request", date, service)
    hashedCanonicalRequest := sha256hex(canonicalRequest)
    string2sign := fmt.Sprintf("%s\\n%d\\n%s\\n%s",
        algorithm,
        timestamp,
        credentialScope,
        hashedCanonicalRequest)
    fmt.Println(string2sign)

    // step 3: sign string
    secretDate := hmacsha256(date, "TC3"+secretKey)
    secretService := hmacsha256(service, secretDate)
    secretSigning := hmacsha256("tc3_request", secretService)
    signature := hex.EncodeToString([]byte(hmacsha256(string2sign, secretSigning)))
    fmt.Println(signature)

    // step 4: build authorization
    authorization := fmt.Sprintf("%s Credential=%s/%s, SignedHeaders=%s, Signature=%s",
        algorithm,
        secretId,
        credentialScope,
        signedHeaders,
        signature)
    fmt.Println(authorization)

    curl := fmt.Sprintf(`curl -X POST https://%s\\
 -H "Authorization: %s"\\
 -H "Content-Type: application/json; charset=utf-8"\\
 -H "Host: %s" -H "X-TC-Action: %s"\\
 -H "X-TC-Timestamp: %d"\\
 -H "X-TC-Version: %s"\\
 -H "X-TC-Region: %s"\\
 -d '%s'`, host, authorization, host, action, timestamp, version, region, payload)
    fmt.Println(curl)
}

2. API 3.0 V1バージョンの署名を取得する

署名方式v1はシンプルで使いやすいですが、機能とセキュリティの両方で署名方式v3には劣っています。署名方式v3の使用が推奨されます。
注意：
初めて使用する場合は、API Explorerの「署名文字列生成」機能を使用し、署名バージョンに「API 3.0 署名 v1」を選択することが推奨されます。これにより署名プロセスを生成して検証できるほか、一部のプログラミング言語の署名サンプルを提供します。また、直接的にSDKコードを生成することも可能です。Tencent Cloud API対応の7種類の主要なプログラミング言語向けSDKの使用を推奨します。これらは署名とリクエストプロセスをカプセル化し、すべてオープンソース化されており、Python、Java、PHP、Go、NodeJS、.NET、C++をサポートしています。
CVMのインスタンスリストを表示する（DescribeInstances）リクエストを例として、ユーザーがこのAPIを呼び出す場合、そのリクエストパラメータは以下のようになります：
パラメータ名
中国語
パラメータ値
Action
メソッド名
DescribeInstances
SecretId
シークレットキーID
AKIDz8krbsJ5**********mLPx3EXAMPLE
Timestamp
現在のタイムスタンプ
1465185768
Nonce
ランダムな正の整数
11886
Region
インスタンスのリージョン
ap-guangzhou
InstanceIds.0
照会対象インスタンスID
ins-09dx96dg
Offset
オフセット
0
Limit
最大許容出力
20
Version
APIバージョン番号
2017-03-12

1. パラメータをソートする

まず、すべてのリクエストパラメータをパラメータ名の辞書順（ASCIIコード）で昇順にソートします。
注意：
パラメータ名のみでソートし、パラメータ値は対応関係を保持すればよく、比較対象となりません。
ASCIIコード順で比較し、例えばInstanceIds.2はInstanceIds.12の後ろに配置されます。アルファベット順でも数値順でもありません。ユーザーはプログラミング言語の関連ソート関数（例えばPHPのksort関数）を利用してこの機能を実現できます。
上記のサンプルパラメータのソート結果は以下の通りです：
{
    'Action' : 'DescribeInstances',
    'InstanceIds.0' : 'ins-09dx96dg',
    'Limit' : 20,
    'Nonce' : 11886,  
    'Offset' : 0,
    'Region' : 'ap-guangzhou',
    'SecretId' : 'AKIDz8krbsJ5**********mLPx3EXAMPLE',
    'Timestamp' : 1465185768,
    'Version': '2017-03-12',
}
プログラミング言語を使用して開発する場合、上記のサンプル中のパラメータをソートでき、結果が一致すれば問題ありません。

2. 正規リクエスト文字列の連結

このステップではリクエスト文字列を生成します。前のステップでソートされたリクエストパラメータを「パラメータ名=パラメータ値」の形式にフォーマットします。例えばActionパラメータの場合、パラメータ名は"Action"、パラメータ値は"DescribeInstances"であるため、フォーマット後はAction=DescribeInstancesとなります。
注意：
「パラメータ値」はurlエンコード後の値ではなく、生の値です。
次に、フォーマットされた各パラメータを「&」で連結し、最終的に生成されるリクエスト文字列は次のようになります：
Action=DescribeInstances&InstanceIds.0=ins-09dx96dg&Limit=20&Nonce=11886&Offset=0&Region=ap-guangzhou&SecretId=AKIDz8krbsJ5**********mLPx3EXAMPLE&Timestamp=1465185768&Version=2017-03-12

3. 署名対象文字列を連結する

このステップでは署名原文文字列を生成します。署名原文文字列は以下のパラメータで構成されます：
1. リクエスト方法：POSTおよびGET方式をサポートしています。ここではGETリクエストを使用します。メソッドはすべて大文字であることに注意してください。
2. リクエストホスト：インスタンスリストの表示（DescribeInstances）のリクエストドメインは：cvm.tencentcloudapi.com。実際のリクエストドメインは、APIが属するモジュールによって異なります。詳細は各APIの説明を参照してください。
3. リクエストパス：現在のバージョンのTencentCloud APIのリクエストパスは / に固定されています。
4. リクエスト文字列：前のステップで生成されたリクエスト文字列を指します。
署名原文文字列の連結ルールは：リクエストメソッド + リクエストホスト + リクエストパス + ? + リクエスト文字列です。
サンプルの連結結果は：
GETcvm.tencentcloudapi.com/?Action=DescribeInstances&InstanceIds.0=ins-09dx96dg&Limit=20&Nonce=11886&Offset=0&Region=ap-guangzhou&SecretId=AKIDz8krbsJ5**********mLPx3EXAMPLE&Timestamp=1465185768&Version=2017-03-12

4. 署名を計算する（擬似コード）

このステップでは署名文字列を生成します。まず、HMAC-SHA1アルゴリズムを使用して、前のステップで取得した署名原文文字列に対して署名を行い、次に生成された署名文字列をBase64でエンコードすることで、署名文字列を取得できます。 
hashed := hmac.New(sha1.New, []byte(secretKey))
hashed.Write(buf.Bytes())

fmt.Println(base64.StdEncoding.EncodeToString(hashed.Sum(nil)))

5. 呼び出し情報を取得し、リクエストを送信する

# 実際の呼び出しでは、成功した場合、消費型APIであれば課金が発生します（ここではPython言語を例としてgetリクエストを送信します）
resp = requests.get("https://" + endpoint, params=data)
print(resp.url)
最終的に得られるリクエスト文字列は次のようになります：
https://cvm.tencentcloudapi.com/?Nonce=11886&SecretId=AKIDz8krbsJ5**********mLPx3EXAMPLE&Limit=20&Version=2017-03-12&Offset=0&Action=DescribeInstances&Timestamp=1465185768&Region=ap-guangzhou&Signature=EliP9YW3pW28FpsEdkXt%2F%2BWcGeI%3D&InstanceIds.0=ins-09dx96dg
フィールド名称
説明
endpoint
サービスアドレス、 例：cvm.tencentcloudapi.com
data
API 3.0 署名 V1のサンプルAPIパラメータ。注意 ここでは計算された署名をキー値ペアの形式でdataに追加する必要があります。
注意：
サンプル内のシークレットキーは仮想のものであり、タイムスタンプもシステムの現在時刻ではないため、このurlをブラウザで開くかcurlなどのコマンドで呼び出すと認証エラー（シグネチャの期限切れ）が返されます。正常に応答するurlを取得するには、サンプル内のSecretIdとSecretKeyを実際のキーに置き換え、システムの現在時刻をTimestampとして使用する必要があります。
署名プロセスをより明確に説明するために、以下では Go 言語を例として、上記の署名プロセスを具体的に実装します。リクエストのドメイン、呼び出しのAPIおよびパラメータの値はすべて上記の署名プロセスに準じます。コードは署名プロセスの説明のみを目的としており、汎用性はありません。実際の開発ではできるだけ SDK を使用してください。

6. 署名文字列のエンコーディング

生成された署名文字列は直接リクエストパラメータとして使用することはできません、URLエンコードする必要があります。
前のステップで生成された署名文字列が Eli*****************cGeI= の場合、最終的に得られる署名文字列のリクエストパラメータ（Signature）は：EliP***********************eI%3D となり、これは最終的なリクエストURLの生成に使用されます。
注意：
ユーザーのリクエストメソッドがGETの場合、またはリクエストメソッドがPOSTでかつContent-Typeがapplication/x-www-form-urlencodedである場合、リクエスト送信時にはすべてのリクエストパラメータの値に対してURLエンコードを行う必要があります。パラメータキーと=記号はエンコード不要です。非ASCII文字はURLエンコードを行う前にUTF-8でエンコードする必要があります。
一部のプログラミング言語のネットワークライブラリは、すべてのパラメータに対して自動的にurlencodeを実行します。このような場合、署名文字列に対してURLエンコードを行う必要はありません。さもなければ二重のURLエンコードが行われ、シグネチャ失敗となります。
他のパラメータ値もエンコードが必要です。エンコードは RFC 3986 に準拠します。特殊文字（例：漢字）に対しては %XY 形式のパーセントエンコーディングを使用します。ここで X と Y は16進数文字（0-9および大文字のA-F）です。小文字を使用するとエラーが発生します。

7. API 3.0 シグネチャ V1 サンプル

注意：
ここでは署名の計算部分までです。最終的なリクエスト文字列を取得するには、パラメータparamsに以下の署名キー値を追加する必要があります。
package main

import (
    "bytes"
    "crypto/hmac"
    "crypto/sha1"
    "encoding/base64"
    "net/url"
    "fmt"
    "sort"
)

func main() {
    secretId := "AKIDz8krbsJ5**********mLPx3EXAMPLE"
    secretKey := "Gu5t9xGAR***********EXAMPLE"
    endpoint := "cvm.tencentcloudapi.com"
    params := map[string]string{
        "Nonce":         "11886",
        "Timestamp":     "1465185768",
        "Region":        "ap-guangzhou",
        "SecretId":      secretId,
        "Version":       "2017-03-12",
        "Action":        "DescribeInstances",
        "InstanceIds.0": "ins-09dx96dg",
        "Limit":         "20",
        "Offset":        "0",
    }

    var buf bytes.Buffer
    buf.WriteString("GET")
    buf.WriteString(endpoint)
    buf.WriteString("/")
    buf.WriteString("?")

    // sort keys by ascii asc order
    keys := make([]string, 0, len(params))
    for k, _ := range params {
        keys = append(keys, k)
    }
    sort.Strings(keys)

    for i := range keys {
        k := keys[i]
        buf.WriteString(k)
        buf.WriteString("=")
        buf.WriteString(params[k])
        buf.WriteString("&")
    }
    buf.Truncate(buf.Len() - 1)

    hashed := hmac.New(sha1.New, []byte(secretKey))
    hashed.Write(buf.Bytes())

    signature := base64.StdEncoding.EncodeToString(hashed.Sum(nil))
    fmt.Println(base64.StdEncoding.EncodeToString(hashed.Sum(nil)))
    final_signature := url.QueryEscape(signature)
    fmt.Println(final_signature)
}

署名失敗

以下のシグネチャ失敗のエラーコードが存在します。実際の状況に応じて処理してください。
エラーコード
エラー説明
AuthFailure.SignatureExpire
シグネチャの期限切れです。Timestampとサーバーがリクエストを受信した時間との差は5分を超えてはなりません。
AuthFailure.SecretIdNotFound
シークレットキーが存在しません。コンソールでキーが無効化されていないか、文字を少なくコピーしたか、あるいは多くコピーしたかを確認してください。
AuthFailure.SignatureFailure
シグネチャエラーです。シグネチャの計算エラー、またはシグネチャと実際に送信した内容が一致しない可能性があります。シークレットキー SecretKey のエラーによるものである可能性もあります。
AuthFailure.TokenFailure
一時証明書Tokenエラーです。
AuthFailure.InvalidSecretId
シークレットキーが無効です（TencentCloud APIキータイプではありません）。

レスポンス

正常なレスポンス

CVMのAPIでインスタンスステータスリスト（DescribeInstancesStatus）2017-03-12バージョンを確認する例として、呼び出しが成功すると、返される可能性のある結果は次のとおりです：
{
    "Response": {
        "TotalCount": 0,
        "InstanceStatusSet": [],
        "RequestId": "b5b41468-520d-4192-b42f-595cc34b6c1c"
    }
}
Responseおよびその内部のRequestIdは固定のフィールドであり、リクエストが成功したかどうかに関わらず、APIが処理した限り、必ず返されます。
RequestIdはAPIリクエストの唯一の識別子として使用されます。APIに異常が発生した場合は、該当 ID を添えて連絡してください。
固定フィールド以外は、すべて具体的なAPIで定義されたフィールドです。異なるAPIが返すフィールドについては、APIドキュメントの定義を参照してください。この例のTotalCountとInstanceStatusSetはいずれもDescribeInstancesStatus APIスで定義されたフィールドです。リクエストを呼び出したユーザーが現在CVMインスタンスを保有していないため、TotalCountのこの状況での戻り値は0となり、InstanceStatusSetリストは空です。

エラーレスポンス

呼び出しが失敗した場合、戻り値の例は以下のようになります： 
{
    "Response": {
        "Error": {
            "Code": "AuthFailure.SignatureFailure",
            "Message": "The provided credentials could not be validated. Please check your signature is correct."
        },
        "RequestId": "ed93f3cb-f35e-473f-b9f3-0d451b8b79c6"
    }
}
Errorが出現するということは、そのリクエストの呼び出しが失敗したことを表します。Errorフィールドは、その内部のCodeおよびMessageフィールドとともに、呼び出しが失敗した場合には必ず返されます。
Codeは具体的なエラーコードを示し、リクエストがエラーになった場合、まずこのコードを使用して共通エラーコードリストおよび該当APIのエラーコードリストで原因と解決策を確認できます。
Messageはこのエラーが発生した具体的な原因を表示しますが、業務の発展や体験の最適化に伴い、このテキストは頻繁に変更または更新される可能性があります。ユーザーはこの戻り値に依存すべきではありません。
RequestIdはAPIリクエストの唯一の識別子として使用されます。APIに異常が発生した場合は、該当 ID を添えて連絡してください。

共通エラーコード

戻り結果にErrorフィールドが存在する場合、APIの呼び出しが失敗したことを示します。Error内のCodeフィールドはエラーコードを表し、すべての業務で発生する可能性のあるエラーコードは共通エラーコードです。以下の表に共通エラーコードをリストアップします。
エラーコード
エラー説明
AuthFailure.InvalidSecretId
キーが無効です（TencentCloud APIキータイプではありません）。
AuthFailure.MFAFailure
MFAエラーです。
AuthFailure.SecretIdNotFound
シークレットキーが存在しません。
AuthFailure.SignatureExpire
シグネチャの期限切れです。
AuthFailure.SignatureFailure
シグネチャエラーです。
AuthFailure.TokenFailure
tokenエラーです。
AuthFailure.UnauthorizedOperation
リクエストはCAM認可が取得されていません。
DryRunOperation
DryRunオペレーションは、リクエストが成功することを意味しますが、余分にDryRunパラメータが渡されただけです。
FailedOperation
操作に失敗しました。
InternalError
内部エラーです。
InvalidAction
APIが存在しません。
InvalidParameter
パラメータエラーです。
InvalidParameterValue
パラメータ値エラーです。
LimitExceeded
クォータ制限を超過しました。
MissingParameter
パラメータ不足エラーです。
NoSuchVersion
APIバージョンが存在しません。
RequestLimitExceeded
リクエスト回数がレート制限を超過しました。
ResourceInUse
リソースが使用中です。
ResourceInsufficient
リソース不足です。
ResourceNotFound
リソースが存在しません。
ResourceUnavailable
リソースは利用不可です。
UnauthorizedOperation
操作は認可されていません。
UnknownParameter
未知パラメータエラーです。
UnsupportedOperation
操作はサポートされていません。
UnsupportedProtocol
HTTPSリクエスト方法が正しくありません。GETとPOSTリクエストのみサポートしています。
UnsupportedRegion
APIは指定されたリージョンをサポートしていません。
前の記事へ: .NET API次の記事へ: Java API

ヘルプとサポート

この記事はお役に立ちましたか？

フィードバック