Volcengine SDK for Python

Common errors

• No module named 'volcengine.ecs.ECSService'

  cause The `volcengine` package or a specific service sub-module is not installed, or the import path is incorrect.
  fix Ensure the `volcengine` package is installed via `pip install volcengine`. Verify the exact import path against the official documentation or examples for the specific service you are trying to use.

• Status code: 401, Error code: SignatureDoesNotMatch

  cause The provided Volcengine AccessKey ID, Secret Access Key, or Region is incorrect or does not match the request signature.
  fix Double-check the `VOLCENGINE_ACCESSKEYID`, `VOLCENGINE_SECRETACCESSKEY`, and `VOLCENGINE_REGION` environment variables or the values passed to `set_ak()`, `set_sk()`, `set_region()` methods. Ensure they correspond to a valid Volcengine account and region.

• AttributeError: 'StsService' object has no attribute 'get_caller_identity'

  cause This usually indicates a typo in the API method name, using an outdated client version, or attempting to call a method that doesn't exist for the service/client.
  fix Verify the exact method name and its arguments in the official API documentation for your SDK version. Ensure your SDK is up to date with `pip install --upgrade volcengine`.

Warnings

• gotcha Authentication requires correct `VOLCENGINE_ACCESSKEYID`, `VOLCENGINE_SECRETACCESSKEY`, and `VOLCENGINE_REGION` environment variables or explicit client configuration. Misconfiguration is the most common cause of API failures.
  Fix: Set the required environment variables (recommended for production) or use `client.set_ak()`, `client.set_sk()`, `client.set_region()` methods directly on the service client instance before making API calls.
• gotcha API request and response objects are typically Protocol Buffer messages, imported from `volcengine.<service_name>.model.<service_name>_pb2`. Failing to use these specific types can lead to `TypeError` or `AttributeError`.
  Fix: Always refer to the specific service's `model` submodule for the correct request and response types, e.g., `from volcengine.sts.model.sts_pb2 import GetCallerIdentityRequest`.
• gotcha Ensure `protobuf` and `grpcio` are correctly installed and compatible. Version mismatches between these core dependencies or with the SDK can lead to cryptic errors during API calls or client initialization.
  Fix: If encountering `TypeError` or `AttributeError` related to message objects or RPC communication, try `pip install --upgrade protobuf grpcio grpcio-tools` to ensure compatible versions.

Install

• pip install volcengine Install stable version

Imports

• StsService

  from volcengine.sts.StsService import StsService

  Import the client for the Security Token Service (STS).
• GetCallerIdentityRequest

  from volcengine.sts.model.sts_pb2 import GetCallerIdentityRequest

  Import specific request models, which are Protocol Buffer messages, from the service's 'model' submodule.
• ECSService

  from volcengine.ecs.ECSService import ECSService

  General pattern for importing a service client, e.g., for Elastic Compute Service (ECS).

Quickstart

This quickstart initializes the Security Token Service (STS) client and calls `GetCallerIdentity` to retrieve the current user's identity. It expects `VOLCENGINE_ACCESSKEYID`, `VOLCENGINE_SECRETACCESSKEY`, and `VOLCENGINE_REGION` to be set as environment variables.

import os
from volcengine.sts.StsService import StsService
from volcengine.sts.model.sts_pb2 import GetCallerIdentityRequest

# Initialize STS service client with credentials from environment variables
sts_service = StsService()
sts_service.set_ak(os.environ.get("VOLCENGINE_ACCESSKEYID", ""))
sts_service.set_sk(os.environ.get("VOLCENGINE_SECRETACCESSKEY", ""))
sts_service.set_region(os.environ.get("VOLCENGINE_REGION", "cn-beijing")) # Default to cn-beijing if not set

# Create a request object
req = GetCallerIdentityRequest()

try:
    # Call the API
    resp = sts_service.get_caller_identity(req)
    # Print the response
    print("Successfully called GetCallerIdentity:")
    print(f"  Account ID: {resp.AccountId}")
    print(f"  User ID: {resp.UserId}")
    print(f"  User Name: {resp.UserName}")
except Exception as e:
    print(f"Error calling GetCallerIdentity: {e}")