Alibaba Cloud SDK を使用すると、アプリケーションから OpenAPI オペレーションを呼び出す際の開発や機能統合が簡素化されます。このトピックでは、SDK のインストール、アクセス認証情報の設定、SDK の使用方法といった統合フロー全体について説明します。また、ファイルのアップロードのための Advance API やよくある質問 (FAQ) についても説明します。
前提条件
-
Python:Python 3.7 以降。
-
アクセスキーペア:Alibaba Cloud OpenAPI を呼び出すには、アクセスキーペアが必要です。このアクセスキーペアに関連付けられた Resource Access Management (RAM) ユーザーには、対象の API オペレーションを呼び出すための権限が必要です。権限がない場合、呼び出しは "You are not authorized to perform this operation" というエラーで失敗します。
-
SDK パッケージ:このトピックの主な例では、
alibabacloud_dysmsapi20180501、alibabacloud_tea_openapi、alibabacloud_tea_utilパッケージが必要です。
SDK のインストール
SDK センターでは、各製品の SDK インストール方法が提供されています。SDK を入手してインストールするには、次の手順に従ってください。
-
SDK センターにログインします。
-
Short Message Service (SMS) などの、API を呼び出す製品を選択します。
-
[Installation] ページで、[All Languages] で [Python] を選択します。
-
[使用開始] タブで、Short Message Service (SMS) の SDK インストール方法を見つけ、SDK をインストールします。
アクセス認証情報の設定
Alibaba Cloud OpenAPI の呼び出しには、通常、アクセス認証情報が必要です。一般的な認証情報の種類は、AccessKey (AK) と Security Token Service (STS) トークンです。認証情報の漏洩を防ぐため、一般的には認証情報を環境変数に保存します。セキュリティのベストプラクティスに関する詳細については、「アクセス認証情報の安全な使用」をご参照ください。
このトピックでは、アクセスキーペアを例として使用します。次の例では、ALIBABA_CLOUD_ACCESS_KEY_ID と ALIBABA_CLOUD_ACCESS_KEY_SECRET という環境変数を使用します。
Linux および macOS での設定
Linux と macOS での Alibaba Cloud AccessKey の環境変数設定
このセクションでは、環境変数 ALIBABA_CLOUD_ACCESS_KEY_ID と ALIBABA_CLOUD_ACCESS_KEY_SECRET を例に説明します。必要に応じて、変数名を OSS_ACCESS_KEY_ID や OSS_ACCESS_KEY_SECRET などに置き換えることができます。
export コマンドを使用して環境変数を設定します。
export コマンドで設定した一時的な環境変数は、現在のセッションでのみ有効です。セッションが終了すると、変数はクリアされます。長期保存 (LTR) するには、export コマンドをオペレーティングシステムの起動設定ファイルに追加してください。
AccessKey ID を設定し、Enter キーを押します。
# yourAccessKeyID を実際の AccessKey ID に置き換えてください。 export ALIBABA_CLOUD_ACCESS_KEY_ID=yourAccessKeyIDAccessKey シークレットを設定し、Enter キーを押します。
# yourAccessKeySecret を実際の AccessKey シークレットに置き換えてください。 export ALIBABA_CLOUD_ACCESS_KEY_SECRET=yourAccessKeySecret設定を確認します。
echo $ALIBABA_CLOUD_ACCESS_KEY_IDコマンドを実行します。コマンドが正しい AccessKey ID を返す場合、設定は成功です。
Windows での設定
Windows での Alibaba Cloud AccessKey の環境変数設定
このセクションでは、環境変数 ALIBABA_CLOUD_ACCESS_KEY_ID と ALIBABA_CLOUD_ACCESS_KEY_SECRET を例に説明します。必要に応じて、変数名を OSS_ACCESS_KEY_ID や OSS_ACCESS_KEY_SECRET などに置き換えることができます。
グラフィカルユーザーインターフェース (GUI) の使用
手順
次の手順では、 Windows 10 の GUI を使用して環境変数を設定する方法について説明します。
デスクトップで [PC] を右クリックし、[プロパティ] > [システムの詳細設定] > [環境変数] の順に選択し、[システム変数] または [ユーザー変数] の [新規] をクリックします。その後、設定を完了します。
変数
値の例
AccessKey ID
変数名: ALIBABA_CLOUD_ACCESS_KEY_ID
変数値: yourAccessKeyID
AccessKey シークレット
変数名: ALIBABA_CLOUD_ACCESS_KEY_SECRET
変数値: yourAccessKeySecret
設定の確認
[スタート] から [ファイル名を指定して実行] をクリックするか、キーボードショートカット Win+R を使用します。
cmdと入力し、[OK] をクリックするか Enter キーを押してコマンドプロンプトを開きます。echo %ALIBABA_CLOUD_ACCESS_KEY_ID%コマンドとecho %ALIBABA_CLOUD_ACCESS_KEY_SECRET%コマンドを実行します。コマンドが正しい AccessKey を返す場合、設定は成功です。
コマンドプロンプト (CMD) の使用
手順
コマンドプロンプトを管理者として開き、次のコマンドを実行して、新しい環境変数をシステムに追加します。
setx ALIBABA_CLOUD_ACCESS_KEY_ID yourAccessKeyID /M setx ALIBABA_CLOUD_ACCESS_KEY_SECRET yourAccessKeySecret /M/Mパラメータは、システム環境変数を示します。ユーザー環境変数を設定する場合は、このパラメータを省略できます。設定の確認
[スタート] から [ファイル名を指定して実行] をクリックするか、キーボードショートカット Win+R を使用します。
cmdと入力し、[OK] をクリックするか Enter キーを押してコマンドプロンプトを開きます。echo %ALIBABA_CLOUD_ACCESS_KEY_ID%コマンドとecho %ALIBABA_CLOUD_ACCESS_KEY_SECRET%コマンドを実行します。コマンドが正しい AccessKey を返す場合、設定は成功です。
Windows PowerShell の使用
PowerShell では、すべての新しいセッションで有効な新しい環境変数を設定できます。
[System.Environment]::SetEnvironmentVariable('ALIBABA_CLOUD_ACCESS_KEY_ID', 'yourAccessKeyID', [System.EnvironmentVariableTarget]::User)
[System.Environment]::SetEnvironmentVariable('ALIBABA_CLOUD_ACCESS_KEY_SECRET', 'yourAccessKeySecret', [System.EnvironmentVariableTarget]::User)すべてのユーザーに対して環境変数を設定するには、管理者権限が必要です。
[System.Environment]::SetEnvironmentVariable('ALIBABA_CLOUD_ACCESS_KEY_ID', 'yourAccessKeyID', [System.EnvironmentVariableTarget]::Machine)
[System.Environment]::SetEnvironmentVariable('ALIBABA_CLOUD_ACCESS_KEY_SECRET', 'yourAccessKeySecret', [System.EnvironmentVariableTarget]::Machine)現在のセッションでのみ有効な一時的な環境変数を設定できます。
$env:ALIBABA_CLOUD_ACCESS_KEY_ID = "yourAccessKeyID"
$env:ALIBABA_CLOUD_ACCESS_KEY_SECRET = "yourAccessKeySecret"PowerShell で、 Get-ChildItem env:ALIBABA_CLOUD_ACCESS_KEY_ID コマンドと Get-ChildItem env:ALIBABA_CLOUD_ACCESS_KEY_SECRET コマンドを実行します。コマンドが正しい AccessKey を返す場合、設定は成功です。
環境変数を設定した後、新しい設定を有効にするために、統合開発環境 (IDE) などの開発ツールやサービスの再起動が必要な場合があります。
SDK の使用
標準の呼び出しフローは、ほとんどのシナリオで使用できます。一部のクラウド製品は、標準の OpenAPI オペレーションによる直接のファイルアップロードをサポートしていません。これらの製品にファイルをアップロードするには、Advance API を使用します。「Advance API を使用したファイルのアップロード」をご参照ください。
このトピックでは、Short Message Service (SMS) の SendMessageToGlobe API を例として使用します。SendMessageToGlobe API のリファレンスについては、「SendMessageToGlobe」をご参照ください。
リクエストクライアントの初期化
すべての OpenAPI 呼び出しは、SDK が提供するリクエストクライアント (Client) を介して行います。OpenAPI オペレーションを呼び出す前に、リクエストクライアントを初期化します。リクエストクライアントは、複数の初期化メソッドをサポートしています。この例では、アクセスキーペアを使用します。その他の初期化メソッドについては、「アクセス認証情報の管理」をご参照ください。
-
クライアントオブジェクトはスレッドセーフです。たとえば、マルチスレッド環境で 1 つのDysmsapi20180501Client インスタンスを安全に共有できます。スレッドごとに個別のインスタンスを作成する必要はありません。
-
クライアントオブジェクトを頻繁に作成しないでください。頻繁に作成すると、リソースが無駄になり、パフォーマンスが低下します。(推奨) シングルトンパターンを使用してクライアントをラップし、アプリケーションのライフサイクルを通じて、同じアクセス認証情報とエンドポイントに対してクライアントインスタンスが 1 つだけ初期化されるようにしてください。
@staticmethod
def create_client() -> Dysmsapi20180501Client:
config = open_api_models.Config(
# 必須。ALIBABA_CLOUD_ACCESS_KEY_ID 環境変数が設定されていることを確認してください。
access_key_id=os.environ['ALIBABA_CLOUD_ACCESS_KEY_ID'],
# 必須。ALIBABA_CLOUD_ACCESS_KEY_SECRET 環境変数が設定されていることを確認してください。
access_key_secret=os.environ['ALIBABA_CLOUD_ACCESS_KEY_SECRET']
)
# https://api.alibabacloud.com/product/Dysmsapi をご参照ください。
config.endpoint = f'dysmsapi.aliyuncs.com'
return Dysmsapi20180501Client(config)
リクエストオブジェクトの作成
OpenAPI オペレーションを呼び出すときにパラメーターを渡すには、SDK が提供するリクエストオブジェクトを使用します。リクエストオブジェクトの名前は <API オペレーション名>Request 形式です。リクエストパラメーターの詳細については、対応する API ドキュメントをご参照ください。この例で使用されている API ドキュメントについては、「SendMessageToGlobe」をご参照ください。
OpenAPI オペレーションがリクエストパラメーターをサポートしていない場合は、リクエストオブジェクトを作成する必要はありません。たとえば、DescribeCdnSubList API はリクエストパラメーターをサポートしていません。
# リクエストオブジェクトを作成し、必須の入力パラメーターを設定します。
send_message_to_globe_request = dysmsapi_20180501_models.SendMessageToGlobeRequest(
# 受信者の番号に置き換えてください。
to='<YOUR_NUMBER>',
# SMS コンテンツに置き換えてください。
message='<YOUR_MESSAGE>'
)
リクエストの送信
(推奨) リクエストを送信するには、<api_name>_with_options 関数を呼び出します。ここで、<api_name> はスネークケースの OpenAPI 名です。この関数は、前の手順で作成したリクエストオブジェクトとランタイムオプションオブジェクトの 2 つのパラメーターを受け取ります。ランタイムオプションオブジェクトは、タイムアウト設定やプロキシ設定など、リクエストの動作を設定します。詳細については、「高度な設定」をご参照ください。
リクエストが成功すると、関数はレスポンスオブジェクトを返します。レスポンスを出力またはログに記録して、呼び出し結果を検証してください。
OpenAPI オペレーションがリクエストパラメーターをサポートしていない場合は、リクエストを送信する際にリクエストオブジェクトを渡す必要はありません。たとえば、DescribeCdnSubList API を呼び出す場合、ランタイムオプションのみを渡します。
# ランタイムパラメーターを作成します。
runtime = util_models.RuntimeOptions()
client = create_client()
# リクエストを送信します。
client.send_message_to_globe_with_options(send_message_to_globe_request, runtime)
例外の処理
V2.0 Python SDK は、例外を主に 2 つのタイプに分類します。
-
TeaUnretryableException:主にネットワークの問題が原因で、ネットワークの再試行が最大再試行回数に達した後に発生します。
-
TeaException:主にサービス側のビジネスエラーに対して発生します。
例外処理の詳細については、「例外処理」をご参照ください。
システムの堅牢性と安定性を確保するために、例外の伝播、ログの記録、回復の試行など、例外を処理するための適切な措置を講じてください。
完全なコード例
次の例は、リクエストクライアントの初期化、リクエストオブジェクトの作成、リクエストの送信、例外の処理といった前述の手順を組み合わせたものです。
API 呼び出しの例
import os
import sys
from typing import List
from alibabacloud_dysmsapi20180501.client import Client as Dysmsapi20180501Client
from alibabacloud_tea_openapi import models as open_api_models
from alibabacloud_dysmsapi20180501 import models as dysmsapi_20180501_models
from alibabacloud_tea_util import models as util_models
from alibabacloud_tea_util.client import Client as UtilClient
class Sample:
def __init__(self):
pass
@staticmethod
def create_client() -> Dysmsapi20180501Client:
config = open_api_models.Config(
# 必須。ALIBABA_CLOUD_ACCESS_KEY_ID 環境変数が設定されていることを確認してください。
access_key_id=os.environ['ALIBABA_CLOUD_ACCESS_KEY_ID'],
# 必須。ALIBABA_CLOUD_ACCESS_KEY_SECRET 環境変数が設定されていることを確認してください。
access_key_secret=os.environ['ALIBABA_CLOUD_ACCESS_KEY_SECRET']
)
# https://api.alibabacloud.com/product/Dysmsapi をご参照ください。
config.endpoint = f'dysmsapi.aliyuncs.com'
return Dysmsapi20180501Client(config)
@staticmethod
def main(
args: List[str],
) -> None:
client = Sample.create_client()
# リクエストオブジェクトを作成し、必須の入力パラメーターを設定します。
send_message_to_globe_request = dysmsapi_20180501_models.SendMessageToGlobeRequest(
# 受信者の番号に置き換えてください。
to='<YOUR_NUMBER>',
# SMS コンテンツに置き換えてください。
message='<YOUR_MESSAGE>'
)
# ランタイムパラメーターを作成します。
runtime = util_models.RuntimeOptions()
try:
# リクエストを送信します。
send_message_to_globe_response = client.send_message_to_globe_with_options(send_message_to_globe_request, runtime)
# API レスポンスを出力して結果を検証します。
print(send_message_to_globe_response)
except Exception as error:
# このエラー処理は出力およびデモ用です。実際のプロジェクトでは例外を慎重に処理し、決して無視しないでください。
# エラーメッセージ。
error_message = getattr(error, 'message', str(error))
print(error_message)
# 診断 URL。
print(getattr(error, 'data', {}).get("Recommend"))
UtilClient.assert_as_string(error_message)
if __name__ == '__main__':
Sample.main(sys.argv[1:])
Advance API を使用したファイルのアップロード
Image Search や Visual Intelligence API などの一部のクラウド製品は、公式ドキュメントに記載されている標準の OpenAPI オペレーションによる直接のファイルアップロードをサポートしていません。これらの製品にファイルをアップロードするには、クラウド製品が提供する Advance API を使用します。Advance API はファイルストリームオブジェクトを受け取ります。内部では、クラウド製品はアップロードされたファイルを Alibaba Cloud OSS に一時的に保存します。デフォルトのストレージリージョンは cn-shanghai です。クラウド製品は OSS から一時ファイルを読み取って機能を提供します。次の例では、Alibaba Cloud Visual Intelligence API の Face and Body サービスの DetectBodyCount API を使用します。
Alibaba Cloud OSS に保存されている一時ファイルは定期的にクリーンアップされます。
リクエストクライアントの初期化
リクエストクライアントを初期化する際に、region_id と製品の エンドポイント の両方を設定してください。region_id は OSS 内の一時ファイルのストレージリージョンを指定します。region_id が設定されていない場合、製品と OSS が異なるリージョンに存在する可能性があり、OpenAPI オペレーションを呼び出すときにタイムアウトが発生する可能性があります。
def create_client() -> facebody20191230Client:
config = open_api_models.Config(
# 必須。コード実行環境で ALIBABA_CLOUD_ACCESS_KEY_ID 環境変数が設定されていることを確認してください。
access_key_id=os.environ['ALIBABA_CLOUD_ACCESS_KEY_ID'],
# 必須。コード実行環境で ALIBABA_CLOUD_ACCESS_KEY_SECRET 環境変数が設定されていることを確認してください。
access_key_secret=os.environ['ALIBABA_CLOUD_ACCESS_KEY_SECRET']
)
# エンドポイントと regionId は同じリージョンに設定する必要があります。
config.region_id = 'cn-shanghai'
config.endpoint = 'facebody.cn-shanghai.aliyuncs.com'
return facebody20191230Client(config)
リクエストオブジェクトの作成
ファイルストリームを渡すために <OpenAPIName>AdvanceRequest リクエストオブジェクトを作成してください。パラメーター名は ImageURLObject に固定されています。
# ファイルをバイナリ ストリームとして開きます。
with open('<FILE_PATH>', "rb") as f: # お使いのファイルパスに置き換えてください。
# リクエストパラメーターを設定します。
detect_body_count_advance_request = facebody_20191230_models.DetectBodyCountAdvanceRequest(
image_urlobject=f,
)
リクエストの送信
リクエストを送信するには、<apiName>Advance 関数を呼び出します。ここで、<apiName> はローワーキャメルケースの OpenAPI 名です。
# ランタイム設定。
runtime = util_models.RuntimeOptions()
client = create_client()
# リクエストを送信します。
res = client.detect_body_count_advance(detect_body_count_advance_request, runtime)
次の例は、Advance API を使用してファイルをアップロードするための完全なコードを示しています。
import os
from alibabacloud_facebody20191230 import models as facebody_20191230_models
from alibabacloud_facebody20191230.client import Client as facebody20191230Client
from alibabacloud_tea_openapi import models as open_api_models
from alibabacloud_tea_util import models as util_models
class Sample:
def __init__(self):
pass
@staticmethod
def create_client() -> facebody20191230Client:
config = open_api_models.Config(
# 必須。コード実行環境で ALIBABA_CLOUD_ACCESS_KEY_ID 環境変数が設定されていることを確認してください。
access_key_id=os.environ['ALIBABA_CLOUD_ACCESS_KEY_ID'],
# 必須。コード実行環境で ALIBABA_CLOUD_ACCESS_KEY_SECRET 環境変数が設定されていることを確認してください。
access_key_secret=os.environ['ALIBABA_CLOUD_ACCESS_KEY_SECRET']
)
config.region_id = 'cn-shanghai'
config.endpoint = 'facebody.cn-shanghai.aliyuncs.com'
return facebody20191230Client(config)
@staticmethod
def main() -> None:
client = Sample.create_client()
# ファイルをバイナリ ストリームとして開きます。
with open('<FILE_PATH>', "rb") as f: # をお使いのファイルパスに置き換えてください。
# リクエストパラメーターを設定します。
detect_body_count_advance_request = facebody_20191230_models.DetectBodyCountAdvanceRequest(
image_urlobject=f,
)
runtime = util_models.RuntimeOptions()
try:
# リクエストを送信します。
res = client.detect_body_count_advance(detect_body_count_advance_request, runtime)
print(res)
except Exception as error:
# このエラー処理は出力およびデモ用です。実際のプロジェクトでは例外を慎重に処理し、決して無視しないでください。
print(error)
if __name__ == '__main__':
Sample.main()
よくある質問
"You are not authorized to perform this operation"
原因:アクセスキーペアに関連付けられた RAM ユーザーに、この API オペレーションを呼び出す権限がありません。
解決策:必要な OpenAPI 権限を RAM ユーザーに付与してください。RAM ユーザーに権限を付与する方法の詳細については、「RAMユーザーの権限管理」をご参照ください。
たとえば、RAM ユーザーに対応する権限がない場合、SendMessageToGlobe API の呼び出しでこのエラーが発生します。次のようなカスタム権限ポリシーを作成し、対応する権限を RAM ユーザーに付与してください。
{
"Version": "1",
"Statement": [
{
"Effect": "Allow",
"Action": "dysms:SendMessageToGlobe",
"Resource": "*"
}
]
}
"SDK.EndpointResolvingError"
原因:呼び出す OpenAPI オペレーションが、リクエストクライアントの初期化時に指定されたエンドポイントをサポートしていません。
解決策:「エンドポイント設定」を確認し、エンドポイントをサポートされている値に更新してから、再度 OpenAPI オペレーションを呼び出してください。
AccessKey に関連する AttributeError または KeyError
OpenAPI の呼び出しで AttributeError: 'AttributeError' object has no attribute 'message' または KeyError: 'ALIBABA_CLOUD_ACCESS_KEY_ID' エラーが報告されることがあります。
原因:アクセスキーペアが正しく渡されていません。
解決策:リクエストクライアントを初期化する際に、アクセスキーペアが正しく渡されているかどうかを確認してください。os.environ["XXX"] は環境変数から XXX の値を取得することに注意してください。
SDK の使用中に発生するエラーのその他の解決策については、「よくある質問 (FAQ)」をご参照ください。