Skip to content

Latest commit

 

History

History
410 lines (322 loc) · 16.1 KB

README.md

File metadata and controls

410 lines (322 loc) · 16.1 KB
Raw

English | 简体中文

Huawei Cloud Php Software Development Kit (Php SDK)

The Huawei Cloud Php SDK allows you to easily work with Huawei Cloud services such as Elastic Compute Service (ECS) and Virtual Private Cloud(VPC) without the need to handle API related tasks.

This document introduces how to obtain and use Huawei Cloud Php SDK.

Requirements

  • To use Huawei Cloud Php SDK, you must have Huawei Cloud account as well as the Access Key (AK) and Secret key (SK) of the Huawei Cloud account. You can create an Access Key in the Huawei Cloud console. For more information, see My Credentials.

  • To use Huawei Cloud Php SDK to access the APIs of specific service, please make sure you do have activated the service in Huawei Cloud console if needed.

  • Huawei Cloud Php SDK requires **PHP 5.6, PHP6, PHP7 **, but not support PHP8. Please run command php --version to check the version of Php before run php sdk code.

Install Php SDK

The recommended way to install SDK is with Composer.

Composer is a dependency management tool for Php which allows you to declare the dependencies your project needs and installs them into your project.

# Install Composer
curl -sS https://getcomposer.org/installer | php
    
# Install the Php SDK
composer require huaweicloud/huaweicloud-sdk-php:3.0.3-beta

After installing, you need to require Composer's autoloader:

require 'path/to/vendor/autoload.php';

You can get the SDK version information through SDK center or Packagist.

Code example

  • The following example shows how to query a list of IAM in a specific region, you need to substitute your real {Service}Client for IamClient in actual use.
  • Substitute the values for {your ak string}, {your sk string}, {your endpoint string} and {your domain id}.
<?php

require_once ".\\vendor\autoload.php";

use HuaweiCloud\SDK\Core\Auth\GlobalCredentials;
use HuaweiCloud\SDK\Core\Http\HttpConfig;
use HuaweiCloud\SDK\Core\Exceptions\ConnectionException;
use HuaweiCloud\SDK\Core\Exceptions\RequestTimeoutException;
use HuaweiCloud\SDK\Core\Exceptions\ServiceResponseException;
use HuaweiCloud\SDK\Iam\V3\IamClient;
use HuaweiCloud\SDK\Iam\V3\Model\ListPermanentAccessKeysRequest;
use Monolog\Logger;

//Do not hard-code authentication information into the code, as this may pose a security risk
$ak = getenv("HUAWEICLOUD_SDK_AK");
$sk = getenv("HUAWEICLOUD_SDK_SK");
$endpoint = "{your endpoint}";
$domainId = "{your domain id}";

$config = HttpConfig::getDefaultConfig();
$config->setIgnoreSslVerification(true);
$credentials = new GlobalCredentials($ak,$sk,$domainId);

$iamClient = IamClient::newBuilder()
    ->withHttpConfig($config)
    ->withEndpoint($endpoint)
    ->withCredentials($credentials)
    ->withStreamLogger($stream = 'php://stdout',$logLevel =Logger::INFO)
    ->withFileLogger($logPath='./test_log.txt', $logLevel = Logger::INFO)
    ->build();

function listPermanentAccessKeys($iamClient)
{
    $listPermanentAccessKeysRequest = new ListPermanentAccessKeysRequest(array('userId'=>"{your user id}"));
    try {
        $response = $iamClient->listPermanentAccessKeys($listPermanentAccessKeysRequest);
        echo "\n";
        echo $response;
    } catch (ConnectionException $e) {
        $msg = $e->getMessage();
        echo "\n". $msg ."\n";
    } catch (RequestTimeoutException $e) {
        $msg = $e->getMessage();
        echo "\n". $msg ."\n";
    } catch (ServiceResponseException $e) {
        echo "\n";
        echo $e->getHttpStatusCode(). "\n";
        echo $e->getRequestId(). "\n";        
        echo $e->getErrorCode() . "\n";
        echo $e->getErrorMsg() . "\n";
    }
}
listPermanentAccessKeys($iamClient);

Online Debugging

API Explorer provides api retrieval, SDK samples and online debugging, supports full fast retrieval, visual debugging, help document viewing, and online consultation.

Changelog

Detailed changes for each released version are documented in the CHANGELOG.md.

User Manual 🔝

1. Client Configuration 🔝

1.1 Default Configuration 🔝

// Use default configuration
$config = HttpConfig::getDefaultConfig();

1.2 Network Proxy 🔝

// Use network proxy if needed
$config->setProxyProtocol('http');
$config->setProxyHost('proxy.huawei.com');
$config->setProxyPort(8080);
// In this example, username and password are stored in environment variables. Please configure the environment variables PROXY_USERNAME and PROXY_PASSWORD before running this example.
$config->setProxyUser(getenv('PROXY_USERNAME'));
$config->setProxyPassword(getenv('PROXY_PASSWORD'));

1.3 Timeout Configuration 🔝

// The default connection timeout is 60 seconds, the default read timeout is 120 seconds. You could change it if needed.
$config->setTimeout(120);
$config->setConnectionTimeout(60);

1.4 SSL Certification 🔝

// Skip SSL certification checking while using https protocol if needed
$config->setIgnoreSslVerification(true);
// Server ca certification if needed
$config->setCertFile($yourCertFile);

2. Credentials Configuration 🔝

There are two types of Huawei Cloud services, regional services and global services.

Global services only contain IAM.

For regional services' authentication, project_id is required.

For global services' authentication, domain_id is required.

Parameter description:

  • ak is the access key ID for your account.
  • sk is the secret access key for your account.
  • project_id is the ID of your project depending on your region which you want to operate.
  • domain_id is the account ID of Huawei Cloud.
  • security_token is the security token when using temporary AK/SK.

2.1 Use Permanent AK&SK 🔝

// Regional services
$basicCredentials = new BasicCredentials($ak,$sk,$projectId);
    
// Global services
$globalCredentials = new GlobalCredentials($ak,$sk,$domainId);

2.2 Use Temporary AK&SK 🔝

It's required to obtain temporary AK&SK and security token first, which could be obtained through permanent AK&SK or through an agency.

// Regional services
$basicCredentials = BasicCredentials(ak, sk, projectId).withSecurityToken(securityToken);
    
// Global services
$globalCredentials = GlobalCredentials(ak, sk, domainId).withSecurityToken(securityToken);

3. Client Initialization 🔝

3.1 Initialize the {Service}Client with specified Endpoint 🔝

// Initialize specified service client instance, take IamClient for example
$iamClient = IamClient::newBuilder()
    ->withHttpConfig($config)
    ->withEndpoint($endpoint)
    ->withCredentials($globalCredentials)
    ->build();

where:

4. Send Requests and Handle Responses 🔝

// Initialize a request and print response, take interface of listPermanentAccessKeys for example
$request = new ListPermanentAccessKeysRequest(array(userId=>"{your user id}"));
$response = $iamClient->listPermanentAccessKeys($request);
echo response;

4.1 Exceptions 🔝

Level 1 Notice Level 2 Notice
ConnectionException Connection error HostUnreachableException Host is not reachable
SslHandShakeException SSL certification error
RequestTimeoutException Request timeout CallTimeoutException timeout for single request
RetryOutageException no response after retrying
ServiceResponseException service response error ServerResponseException server inner error, http status code: [500,]
ClientRequestException invalid request, http status code: [400? 500) 
// handle exceptions
try {
    $request = new ListPermanentAccessKeysRequest(array(userId=>"{your user id}"));
    $response = $iamClient->listPermanentAccessKeys($request);
} catch (ConnectionException $e) {
    $msg = $e->getMessage();
    echo "\n". $msg ."\n";
} catch (RequestTimeoutException $e) {
    $msg = $e->getMessage();
    echo "\n". $msg ."\n";
} catch (ServiceResponseException $e) {
    echo "\n";
    echo $e->getHttpStatusCode(). "\n";
    echo $e->getRequestId(). "\n";    
    echo $e->getErrorCode(). "\n";
    echo $e->getErrorMsg(). "\n";
}

5. Use Asynchronous Client 🔝

// Initialize asynchronous client, take IAMAsyncClient for example
$iamClient = IamAsyncClient::newBuilder()
    ->withHttpConfig($config)
    ->withEndpoint($endpoint)
    ->withCredentials($credentials)
    ->build();

// send asynchronous request
$request = new ShowPermanentAccessKeyRequest(array('accessKey' => "{your access key}"));
$promise = $iamClient->showPermanentAccessKeyAsync($request);

// get asynchronous response
$response = $promise->wait();

6. Troubleshooting 🔝

SDK supports Access log and Debug log which could be configured manually.

6.1 Access Log 🔝

SDK supports print access log which could be enabled by manual configuration, the log could be output to the console or specified files.

For example:

$iamClient = IamClient::newBuilder()
    ->withHttpConfig($config)
    ->withEndpoint($endpoint)
    ->withCredentials($globalCredentials)
    ->withStreamLogger($stream = 'php://stdout',$logLevel =Logger::INFO) // Write log to files
    ->withFileLogger($logPath='./test_log.txt', $logLevel = Logger::INFO) // Write log to console
    ->build();

where:

  • withFileLogger:
    • $logPath: log file path.
    • $logLevel: log level, default is INFO.
    • $logMaxFiles: count of log file, default is 5.
  • withStreamLogger:
    • $stream: stream object, default is sys.stdout.
    • $logLevel: log level, default is INFO.

After enabled log, the SDK will print the access log by default, every request will be recorded to the console like:

[2020-10-16 03:10:29][INFO] "GET https://iam.cn-north-1.myhuaweicloud.com/v3.0/OS-CREDENTIAL/credentials/W8VHHFEFPIJV6TFOUOQO" 200 244 7a68399eb8ed63fc91018426a7c4b8a0

The format of access log is:

"{httpMethod} {uri}" {httpStatusCode} {responseContentLength} {requestId}

6.2 Original HTTP Listener 🔝

In some situation, you may need to debug your http requests, original http request and response information will be needed. The SDK provides a listener function to obtain the original encrypted http request and response information.

⚠️ Warning: The original http log information is used in debugging stage only, please do not print the original http header or body in the production environment. These log information is not encrypted and contains sensitive data such as the password of your ECS virtual machine, or the password of your IAM user account, etc. When the response body is binary content, the body will be printed as "***" without detailed information.

$requestHandler = function ($argsMap) {
    if (isset($argsMap['request'])) {
        $sdkRequest = $argsMap['request'];
        $requestHeaders = $sdkRequest->headerParams;
        $requestBase = "> Request " . $sdkRequest->method . ' ' .
            $sdkRequest->url . "\n";
        if (count($requestHeaders) > 0) {
            $requestBase = $requestBase . '> Headers:' . "\n";
            foreach ($requestHeaders as $key => $value) {
                $requestBase = $requestBase . '    ' . $key . ' : ' .
                    $value . "\n";
            }
            $requestBase = $requestBase . '> Body: ' .
                $sdkRequest->body . "\n\n";
        }
        if (isset($argsMap['logger'])) {
            $logger = $argsMap['logger'];
            $logger->addDebug($requestBase);
        }
    }
};

$responseHandler = function ($argsMap) {
    if (isset($argsMap['response'])) {
        $response = $argsMap['response'];
        $responseBase = "> Response HTTP/1.1 " .
            $response->getStatusCode() . "\n";
        $responseHeaders = $response->getHeaders();
        if (count($responseHeaders) > 0) {
            $responseBase = $responseBase . '> Headers:' . "\n";
            foreach ($responseHeaders as $key => $value) {
                $valueToString = '';
                if (is_array($value)) {
                    $valueToString = ''.join($value);
                }
                $responseBase = $responseBase . '    ' . $key . ' : '
                    . $valueToString . "\n";
            }
            $responseBody = $response->getBody();
            $responseBase = $responseBase . '> Body: ' . (string)
                $responseBody . "\n\n";
        }
        if (isset($argsMap['logger'])) {
            $logger = $argsMap['logger'];
            $logger->addDebug($responseBase);
        }
    }
};

$httpHandler = new HttpHandler();
$httpHandler->addRequestHandlers($requestHandler);
$httpHandler->addResponseHandlers($responseHandler);

$iamClient = IamClient::newBuilder()
    ->withHttpConfig($config)
    ->withEndpoint($endpoint)
    ->withCredentials(null)
    ->withStreamLogger($stream='php://stdout',$logLevel=Logger::INFO)
    ->withFileLogger($logPath='./test_log.txt', $logLevel=Logger::INFO)
    ->withHttpHandler($httpHandler)
    ->build();

where:

HttpHandler supports method addRequestHandlers and addResponseHandlers.