SDK_Integration.md

English | 中文

Table of Contents

• SDK Integration
• Requirements
• Credentials
  • AK/SK
  • STS Token
  • AssumeRole
• Endpoint Configuration
  • Custom Endpoint
  • Custom RegionId
  • Automatic Endpoint Resolution
• HTTPS Request Configuration
  • Specify Scheme
  • Ignore SSL Verification
  • Specify TLS Version
• HTTP(S) Proxy
  • Configure HTTP(S) Proxy

SDK Integration

When calling APIs, it is recommended to integrate the SDK in your project. Using the SDK simplifies development, speeds up integration, and reduces long-term maintenance costs. Volcengine SDK integration typically includes three steps: importing the SDK, configuring access credentials, and writing API call code.

Requirements

1. PHP version >= 5.5.
2. It is recommended to use Composer for dependency management.

Credentials

For secure access, the Volcengine PHP SDK supports authentication with AK/SK and STS Token.

AK/SK

AK/SK is a pair of permanent access keys created in the Volcengine console. The SDK signs each request to authenticate.

⚠️ Notes

1. Do not embed or expose AK/SK in client-side applications.
2. Use a configuration center or environment variables.
3. Follow least privilege principles.

Example

<?php
require_once(__DIR__ . '/vendor/autoload.php');

$config = \Volcengine\Common\Configuration::getDefaultConfiguration()
    ->setAk("Your AK")
    ->setSk("Your SK")
    ->setRegion("cn-beijing")
    ->setVerifySsl(false)  # optional, default true
    ->setDebug(true)       # optional, default false
    ->setHost('open.volcengineapi.com') # optional, default open.volcengineapi.com
    ->setSchema('https');  # optional, default https

$apiInstance = new \Volcengine\Vpc\API\VPCApi(
    // If you want use custom http client, pass your client which implements `GuzzleHttp\\ClientInterface`.
    // This is optional, `GuzzleHttp\\Client` will be used as default.
    new GuzzleHttp\Client(),
    $config
);

$body = new \Volcengine\Vpc\Model\CreateVpcRequest();
$body->setClientToken("token-123456789")
    ->setCidrBlock("192.168.0.0/16")
    ->setDnsServers(array("10.0.0.1", "10.1.1.2"));

try {
    $result = $apiInstance->createVpc($body);
    $responseMetaData = $result->offsetGet('ResponseMetadata');
    print_r($result);
} catch (Exception $e) {
    echo 'Exception when calling VPCApi->createVpc: ', $e->getMessage(), PHP_EOL;
}

?>

STS Token

STS (Security Token Service) provides temporary credentials (temporary AK/SK and Token).

⚠️ Notes

1. Least privilege.
2. Use a reasonable TTL. Shorter is safer; avoid exceeding 1 hour.

<?php
require_once(__DIR__ . '/vendor/autoload.php');

$config = \Volcengine\Common\Configuration::getDefaultConfiguration()
    ->setAk('Your AK')
    ->setSk('Your SK')
    ->setSessionToken('Your session token')
    ->setRegion("cn-beijing");

$apiInstance = new \Volcengine\Vpc\Api\VPCApi(
    new \GuzzleHttp\Client(),
    $config
);

$body = new \Volcengine\Vpc\Model\CreateVpcRequest();
$body->setClientToken("token-123456789")
    ->setCidrBlock("192.168.0.0/16")
    ->setDnsServers(array("10.0.0.1", "10.1.1.2"));

try {
    $result = $apiInstance->createVpc($body);
    print_r($result);
} catch (Exception $e) {
    echo 'Exception when calling VPCApi->createVpc: ', $e->getMessage(), PHP_EOL;
}

?>

AssumeRole

AssumeRole provides dynamic credentials with automatic refresh.

⚠️ Notes

1. Least privilege.
2. Choose a reasonable TTL; maximum is 12 hours.
3. Use fine-grained roles and policies.

<?php
require_once(__DIR__ . '/vendor/autoload.php');

$sts = new \Volcengine\Common\Auth\Providers\StsProvider(
    "Your ak", // required
    "Your sk", // required
    "Your role name",  // required
    "Your account id", // required
    "cn-beijing", // optional
    "3600", // optional
    "https", // optional
    "sts.volcengineapi.com", // optional
    '{"Statement":[{"Effect":"Allow","Action":["vpc:CreateVpc"],"Resource":["*"],"Condition":{"StringEquals":{"volc:RequestedRegion":["cn-beijing"]}}}]}' // optional
);

try {
    $result = $sts->getCredentials();
    print_r($result);
} catch (Exception $e) {
    echo 'Exception: ', $e->getMessage(), PHP_EOL;
}

?>

Endpoint Configuration

Custom Endpoint

• Default: if endpoint is not specified, the SDK uses automatic endpoint resolution.

<?php
require_once(__DIR__ . '/vendor/autoload.php');

$config = \Volcengine\Common\Configuration::getDefaultConfiguration()
    ->setAk("Your ak")
    ->setSk("Your sk")
    ->setHost('https://open.volcengineapi.com');

Custom RegionId

<?php
require_once(__DIR__ . '/vendor/autoload.php');

$config = \Volcengine\Common\Configuration::getDefaultConfiguration()
    ->setAk("Your ak")
    ->setSk("Your sk")
    ->setRegion("cn-beijing");

Automatic Endpoint Resolution

The SDK can automatically resolve endpoints based on region and service. You can also enable DualStack.

<?php
require_once(__DIR__ . '/vendor/autoload.php');

$config = \Volcengine\Common\Configuration::getDefaultConfiguration()
    ->setAk("Your ak")
    ->setSk("Your sk")
    ->setUseDualStack(true)
    ->setCustomBootstrapRegion([
        'custom_example_region1' => [],
        'custom_example_region2' => [],
    ]);

HTTPS Request Configuration

Specify Scheme

Default: https

<?php
require_once(__DIR__ . '/vendor/autoload.php');

$config = \Volcengine\Common\Configuration::getDefaultConfiguration()
    ->setAk("Your ak")
    ->setSk("Your sk")
    ->setSchema('https');

Ignore SSL Verification

Default: verifySsl=true

<?php
require_once(__DIR__ . '/vendor/autoload.php');

$config = \Volcengine\Common\Configuration::getDefaultConfiguration()
    ->setAk("Your ak")
    ->setSk("Your sk")
    ->setVerifySsl(false);

Specify TLS Version

Use a custom HTTP client to set TLS version.

<?php
require_once(__DIR__ . '/vendor/autoload.php');

$config = \Volcengine\Common\Configuration::getDefaultConfiguration()
    ->setAk("Your ak")
    ->setSk("Your sk")
    ->setRegion('cn-beijing');

$apiInstance = new \Volcengine\Vpc\Api\VPCApi(
    new GuzzleHttp\Client([
        'curl' => [
            CURLOPT_SSLVERSION => CURL_SSLVERSION_TLSv1_2,
        ],
    ]),
    $config
);

HTTP(S) Proxy

Configure HTTP(S) Proxy

<?php
require_once(__DIR__ . '/vendor/autoload.php');

$config = \Volcengine\Common\Configuration::getDefaultConfiguration()
    ->setAk("Your ak")
    ->setSk("Your sk")
    ->setRegion('cn-beijing');

$apiInstance = new \Volcengine\Vpc\Api\VPCApi(
    new GuzzleHttp\Client([
         'proxy' => [
            'http'  => 'http://127.0.0.1:8888',
            'https' => 'http://127.0.0.1:8889'
        ],
    ]),
    $config
);