API操作の呼び出し - - Alibaba Cloud ドキュメントセンター

Smart Access Gateway (SAG) APIリクエストを送信するには、SAGエンドポイントにHTTP GETリクエストを送信する必要があります。呼び出されるAPI操作に対応するリクエストパラメータを追加する必要があります。API操作を呼び出すと、システムはレスポンスを返します。リクエストとレスポンスはUTF-8でエンコードされます。

リクエスト構造

SAG API操作はRPCプロトコルを使用します。 HTTP GETリクエストを送信することで、SAG API操作を呼び出すことができます。

次のリクエスト構文が使用されます:

http://endpoint/?Action=xx&parameters

パラメータの説明:

エンドポイント: SAG APIのエンドポイント。エンドポイントは smartag.cn-shanghai.aliyuncs.com です。
Action: 実行される操作の名前。たとえば、作成したSAGインスタンスを照会するには、Actionパラメータを DescribeSmartAccessGateways に設定する必要があります。
Version: 使用するAPIのバージョン。SAG APIの現在のバージョンは 2018-03-13 です。
パラメータ: 操作のリクエストパラメータ。複数のパラメータはアンパサンド（&）で区切ります。
リクエストパラメータには、共通パラメータと操作固有パラメータの両方が含まれます。共通パラメータには、APIバージョン番号と認証情報が含まれます。

次の例は、SAGで DescribeSmartAccessGateways 操作を呼び出す方法を示しています:

サンプルリクエストは、読みやすくするためにフォーマットされています。



https://smartag.cn-shanghai.aliyuncs.com/?Action=DescribeSmartAccessGateways
&Format=xml
&Version=2018-03-13
&Signature=xxxx%xxxx%3D
&SignatureMethod=HMAC-SHA1
&SignatureNonce=15215528852396
&SignatureVersion=1.0
&AccessKeyId=key-test
&Timestamp=2018-04-01T12:00:00Z

API認証

アカウントのセキュリティを確保するために、RAMユーザーを使用してAPI操作を呼び出すことをお勧めします。 RAMユーザーとしてSAGでAPI操作を呼び出す前に、必要なポリシーを作成してRAMユーザーにアタッチする必要があります。詳細については、「RAM認証」をご参照ください。

署名

セキュリティを確保するために、すべてのAPIリクエストに署名する必要があります。 SAGは、リクエスト署名を使用してAPI呼び出し元のIDを確認します。

SAGは、AccessKeyペアを使用した対称暗号化を実装して、リクエスト送信者のIDを確認します。 AccessKeyペアは、Alibaba CloudアカウントとRAMユーザーに発行されるID資格情報であり、ログオンユーザー名とパスワードに似ています。 AccessKeyペアは、AccessKey IDとAccessKeyシークレットで構成されます。 AccessKey IDはユーザーのIDを確認するために使用され、AccessKeyシークレットは署名文字列の暗号化と確認に使用されます。 AccessKeyシークレットは厳重に管理する必要があります。

リクエストに署名するには、次の手順を実行します:

リクエストパラメータを使用して、正規化されたリクエスト文字列（正規化クエリ文字列）を作成します。
1. リクエストパラメータは、名前のアルファベット順に並べられます（パブリックリクエストパラメータと、このドキュメントで説明されている特定のリクエストインターフェースのユーザー定義パラメータを含みますが、パブリックリクエストパラメータで説明されているSignatureパラメータは除きます）。
  重要 GETメソッドを使用して送信されたリクエストの場合、これらのパラメータはリクエストURLのパラメータセクション（つまり、URLの「?」以降の「&」で接続されたセクション）を構成します。
2. 各リクエストパラメータの名前と値はエンコードされます。名前と値は、UTF-8文字セットを使用してURLエンコードする必要があります。 URLエンコードルールは次のとおりです。
  1. 文字 A-Z、a-z、0-9、および「-」、「_」、「.」、「~」はエンコードされません。
  2. その他の文字は「%XY」形式でエンコードされます。XYは文字のASCIIコードを16進数表記で表します。たとえば、英語の二重引用符（ "）は%22としてエンコードされます。
  3. 拡張UTF-8文字は「%XY%ZA…」形式でエンコードされます。
  4. 英語のスペースは、プラス記号（+）ではなく、%20としてエンコードされることに注意してください。
    重要一般に、URLエンコードをサポートするライブラリ（Javaの java.net.URLEncoderなど）は、MIMEタイプ「application / x-www-form-urlencoded」のルールに従って文字をエンコードします。このエンコード方法を使用する場合は、エンコードされた文字列のプラス記号（+）を%20に、アスタリスク（*）を%2Aに置き換え、%7Eをチルダ（〜）に戻して、上記のエンコードルールに準拠させます。
3. エンコードされたパラメータ名と値を等号（=）で接続します。
4. 等号で接続されたパラメータ名と値のペアをアルファベット順にソートし、それらを（&）記号で接続して、正規化クエリ文字列を作成します。
前の手順で作成した正規化クエリ文字列を使用して、次のルールに従って署名計算に使用する文字列を作成します。
```
StringToSign=
HTTPMethod + "&" +
percentEncode("/") + "&" +
percentEncode(CanonicalizedQueryString)
```
パラメータの説明:
- HTTPMethod: リクエスト送信に使用されるHTTPメソッド。たとえば、GETです。
- percentEncode（ "/"）：1.bで説明されているURLエンコードルールに従ってエンコードされた文字 "/" の値。つまり、「%2F」です。
- percentEncode（CanonicalizedQueryString）：手順1で作成された正規化クエリ文字列のエンコードされた文字列。1.bで説明されているURLエンコードルールに従って作成されます。
上記の署名文字列を使用して、RFC2104定義に基づいて署名のHMAC値を計算します。
重要署名の計算に使用されるキーは、所有しているアクセスキーシークレットです。「&」文字（ASCII：38）で終わり、SHA1ハッシュに基づいています。
Base64エンコードルールに従って、上記のHMAC値を文字列にエンコードします。これが署名値です。
署名をSignatureパラメータとしてリクエストに追加します。結果は署名付きAPIリクエストです。
説明署名が最終的なリクエストパラメータ値としてSAGに送信されるとき、署名はRFC 3986で定義されているルールに基づいてURLエンコードする必要があります。次の例は、リクエストが署名される前の DescribeSmartAccessGateways 操作のリクエストURLを示しています:
```
http://smartag.cn-shanghai.aliyuncs.com/?Timestamp=2016-04-23T12:46:24Z&Format=XML&AccessKeyId=testid&Action=DescribeSmartAccessGateways&SignatureMethod=HMAC-SHA1&RegionId=region1&SignatureNonce=3ee8c1b8-83d3-44af-a94f-4e0ad82fd6cf&Version=2018-03-13&SignatureVersion=1.0
```

次の文字列は、署名対象の文字列です:

GET&%2F&AccessKeyId%3Dtestid&Action%DescribeSmartAccessGateways&Format%3DXML&SignatureMethod%3DHMAC-SHA1&SignatureNonce%3D3ee8c1b8-83d3-44af-a94f-4e0ad82fd6cf&SignatureVersion%3D1.0&Timestamp%3D2018-04-23T12%253A46%253A24Z&Version%3D2018-03-13

この例では、AccessKey IDは testid で、AccessKeyシークレットは testsecret です。署名対象の文字列のHMAC値の計算に使用されるシークレットキーは testsecret& です。署名は CT9X0VtwR86fNWSnsc6v8YGOjuE= です。
次のURLは、署名がSignatureパラメータとしてリクエストに追加された後の署名付きリクエストURLです:
```
http://smartag.cn-shanghai.aliyuncs.com/?Timestamp=2016-04-23T12%3A46%3A24Z&Format=XML&AccessKeyId=testid&Action=DescribeSmartAccessGateways&SignatureMethod=HMAC-SHA1&RegionId=region1&SignatureNonce=3ee8c1b8-83d3-44af-a94f-4e0ad82fd6cf&SignatureVersion=1.0&Version=2018-03-13&Signature=CT9X0VtwR86fNWSnsc6v8YGOjuE%3D
```