公有云對(duì)象存儲(chǔ) S3 C SDK 文檔

一 SDK說(shuō)明

本文主要介紹 公有云對(duì)象存儲(chǔ) C語(yǔ)言 s3-API接口，包括：

• 接口功能和調(diào)用方法
• 接口數(shù)據(jù)類型的定義
• 接口參數(shù)和返回值描述。

二 安裝 SDK

C SDK 名為 libs3，有三種安裝方式:

• 包管理工具安裝
• 源碼編譯安裝
• 壓縮包安裝

2.1 包管理工具安裝（不同系統(tǒng)使用工具有所區(qū)別）

• CentOS、Redhat、fedora

sudo yum install -y libs3*

• debian、ubuntu

sudo apt-get install -y libs3*

會(huì)安裝 libs3、libs3-devel;
SDK依賴的頭文件通常在 /usr/include/libs3.h
SDK依賴的動(dòng)態(tài)庫(kù)通常在 /usr/lib64/libs3.so.2.0
各個(gè)系統(tǒng)會(huì)有所差別

s3 help 
---------------------
s3 is a program for performing single requests to Amazon S3.

 Options:

   Command Line:
   .....

s3安裝成功

• 使用s3 工具，測(cè)試環(huán)境

1. 配置環(huán)境變量

export S3_ACCESS_KEY_ID="your access key"
export S3_SECRET_ACCESS_KEY="your secret key"
export S3_HOSTNAME="your s3 server hostname"

2. 運(yùn)行示例

#獲取用戶所有的bucket信息
s3 -u list 
#獲取 mybucket 下對(duì)象信息
s3 -u list mybucket 

• 開(kāi)發(fā)者調(diào)用libs3接口

請(qǐng)參照 示例代碼
或參照下文

2.2 源碼安裝

由于libs3依賴libxml2和libcurl，所以需要先對(duì)其進(jìn)行安裝。

• 安裝依賴

1. 步驟
   1、下載libxml2(2.9.2版本)
   2、編譯安裝libxml2
   3、下載libcurl(curl-7.48.0版本)
   4、編譯安裝libcurl
2. 代碼

cd;
wget ftp://xmlsoft.org/libxml2/libxml2-2.9.2.tar.gz;
tar -zxvf libxml2-2.9.2.tar.gz;
cd libxml2-2.9.2;
./configure;
make & make install

cd;
wget https://curl.haxx.se/download/curl-7.48.0.tar.gz
tar -zxvf curl-7.48.0.tar.gz
./configure --enable-shared
make 
make install

• 以上依賴包亦可以通過(guò)包管理工具安裝

1. CentOS、Redhat、fedora

sudo yum install -y libxml2*
sudo yum install -y libcurl*

2. debian、ubuntu

sudo apt-get install -y libxml2*
sudo apt-get install -y libcurl*

依賴包安裝完成

• 安裝libs3庫(kù)

1. 步驟
   1、下載libs3-2.0.zip，https://github.com/bji/libs3/tree/2.0 解壓
   2、進(jìn)入libs3-2.0目錄
   3、make
   4、make install

cd;
git clone https://github.com/bji/libs3/tree/2.0;
cd libs3-2.0;
make & make install

2. 驗(yàn)證：

export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:$HOME/libs3-2.0/build/lib ;
s3 help

輸入s3命令，給出命令提示，則證明安裝libs3成功。

2.3 壓縮包安裝

• 聯(lián)系中移物聯(lián)網(wǎng) 開(kāi)放平臺(tái)部工作人員，獲取壓縮包c(diǎn)entos*.zip（不同系統(tǒng)所需的庫(kù)有所區(qū)別）

• 解壓sdk到某個(gè)目錄得到 libs3及相關(guān)依賴庫(kù)

• 解壓完成可以進(jìn)入demo參考示例代碼。其中s3.c包含了所有的示例，samples.c中包含了常用的示例。

可以通過(guò)修改makefile進(jìn)行編譯不同的示例代碼。

• 如果運(yùn)行s3.c示例，需要配置sdk測(cè)試環(huán)境

export S3_ACCESS_KEY_ID="your access key"
export S3_SECRET_ACCESS_KEY="your secret key"
export S3_HOSTNAME="your s3 server hostname"

• 運(yùn)行示例程序

如：在demo目錄下執(zhí)行 ./s3 -u list 獲取用戶所有的bucket信息
./s3 -u list mybucket 獲取bucket下對(duì)象信息
其他示例程序可以通過(guò)輸入./s3 查看詳細(xì)的幫助信息。

• 如果運(yùn)行samples.c示例，需要修改samples.c中以下內(nèi)容：

const char *hostname = "your s3 server hostname";
static const char *accessKeyIdG = "your access key";
static const char *secretAccessKeyG = "your secret key";

• 運(yùn)行示例程序

#獲取用戶所有的bucket信息
cd ~/centosxx/demo/
./s3 -u list 

** 確認(rèn)您已經(jīng)理解對(duì)象存儲(chǔ)基本概念，如s3、Bucket、Object、Endpoint、AccessKey和SecretKey等。**

三 公共接口

#include <libs3.h>

libs3實(shí)現(xiàn)、封裝異步調(diào)用的S3接口，在調(diào)用不同的接口的時(shí)候，都需要進(jìn)行初始化、設(shè)置回調(diào)等步驟，本節(jié)對(duì)這些公共步驟進(jìn)行講解。
*本節(jié)大部分示例代碼引用自 s3.c

3.1 初始化

• 接口描述

1. 功能
   初始化，在調(diào)用具體s3接口函數(shù)之前必須先調(diào)用此函數(shù)對(duì)libs3進(jìn)行初始化。

2. 定義

S3Status S3_initialize(const char *userAgentInfo, int flags,
                       const char *defaultS3HostName);

3. 參數(shù)

• 示例代碼

static void S3_init()
{
    S3Status status;
    const char *hostname = getenv("S3_SERVER_HOSTNAME");
    
    if ((status = S3_initialize("s3", S3_INIT_ALL, hostname)) != S3StatusOK) {
        fprintf(stderr, "Failed to initialize libs3: %s\n", S3_get_status_name(status));
        exit(-1);
    }
}

3.2 取消初始化

• 接口描述

1. 功能
   在調(diào)用初始化函數(shù)后,如不再使用s3,必須使用此函數(shù)進(jìn)行取消初始化。

2. 定義

void S3_deinitialize();

3. 參數(shù)
   無(wú)

• 示例代碼

S3_deinitialize();

3.3 獲取錯(cuò)誤信息

• 接口描述

1. 功能
   獲取錯(cuò)誤描述信息。

2. 定義

const char *S3_get_status_name(S3Status status);

3. 參數(shù)

• 示例代碼

printf(S3_get_status_name(status));

3.4 響應(yīng)回調(diào)函數(shù)

• 接口描述

1. 功能
   響應(yīng)完全接收時(shí)調(diào)用的回調(diào)函數(shù)。

2. 定義

S3Status (S3ResponsePropertiesCallback) (const S3ResponseProperties *properties, void *callbackData);

3. 參數(shù)

• 示例代碼：

static S3Status responsePropertiesCallback
    (const S3ResponseProperties *properties, void *callbackData)
{
    (void) callbackData;

    if (!showResponsePropertiesG) {
        return S3StatusOK;
    }

#define print_nonnull(name, field)                                 \
    do {                                                           \
        if (properties-> field) {                                  \
            printf("%s: %s\n", name, properties-> field);          \
        }                                                          \
    } while (0)
    
    print_nonnull("Content-Type", contentType);
    print_nonnull("Request-Id", requestId);
    print_nonnull("Request-Id-2", requestId2);
    if (properties->contentLength > 0) {
        printf("Content-Length: %lld\n", 
               (unsigned long long) properties->contentLength);
    }
    print_nonnull("Server", server);
    print_nonnull("ETag", eTag);
    if (properties->lastModified > 0) {
        char timebuf[256];
        time_t t = (time_t) properties->lastModified;
        // gmtime is not thread-safe but we don't care here.
        strftime(timebuf, sizeof(timebuf), "%Y-%m-%dT%H:%M:%SZ", gmtime(&t));
        printf("Last-Modified: %s\n", timebuf);
    }
    int i;
    for (i = 0; i < properties->metaDataCount; i++) {
        printf("x-amz-meta-%s: %s\n", properties->metaData[i].name,
               properties->metaData[i].value);
    }

    return S3StatusOK;
}

3.5 響應(yīng)完成回調(diào)函數(shù)

• 接口描述

1. 功能
   響應(yīng)完成時(shí)回調(diào)該函數(shù)。

2. 定義

void (S3ResponseCompleteCallback)(S3Status status, const S3ErrorDetails *errorDetails, void *callbackData);

3. 參數(shù)

• 示例代碼

static void responseCompleteCallback(S3Status status,
                                     const S3ErrorDetails *error, 
                                     void *callbackData)
{
    if (!callbackData) {
        //do something;
    }

    statusG = status;
    // Compose the error details message now, although we might not use it.
    // Can't just save a pointer to [error] since it's not guaranteed to last
    // beyond this callback
    int len = 0;
    if (error && error->message) {
        len += snprintf(&(errorDetailsG[len]), sizeof(errorDetailsG) - len,
                        "  Message: %s\n", error->message);
    }
    if (error && error->resource) {
        len += snprintf(&(errorDetailsG[len]), sizeof(errorDetailsG) - len,
                        "  Resource: %s\n", error->resource);
    }
    if (error && error->furtherDetails) {
        len += snprintf(&(errorDetailsG[len]), sizeof(errorDetailsG) - len,
                        "  Further Details: %s\n", error->furtherDetails);
    }
    if (error && error->extraDetailsCount) {
        len += snprintf(&(errorDetailsG[len]), sizeof(errorDetailsG) - len,
                        "%s", "  Extra Details:\n");
        int i;
        for (i = 0; i < error->extraDetailsCount; i++) {
            len += snprintf(&(errorDetailsG[len]), 
                            sizeof(errorDetailsG) - len, "    %s: %s\n", 
                            error->extraDetails[i].name,
                            error->extraDetails[i].value);
        }
    }
}

3.6 獲取bucket列表回調(diào)函數(shù)

• 接口描述

1. 功能
   獲取bucket列表的回調(diào)函數(shù)。

2. 定義

S3Status (S3ListServiceCallback)(const char *ownerId, 
                                         const char *ownerDisplayName,
                                         const char *bucketName,
                                         int64_t creationDateSeconds,
                                         void *callbackData);

3. 參數(shù)

• 示例代碼

static S3Status listServiceCallback(const char *ownerId, 
                                    const char *ownerDisplayName,
                                    const char *bucketName,
                                    int64_t creationDate, void *callbackData)
{
    list_service_data *data = (list_service_data *) callbackData;

    if (!data->headerPrinted) {
        data->headerPrinted = 1;
        printListServiceHeader(data->allDetails);
    }

    char timebuf[256];
    if (creationDate >= 0) {
        time_t t = (time_t) creationDate;
        strftime(timebuf, sizeof(timebuf), "%Y-%m-%dT%H:%M:%SZ", gmtime(&t));
    }
    else {
        timebuf[0] = 0;
    }

    printf("%-56s  %-20s", bucketName, timebuf);
    if (data->allDetails) {
        printf("  %-64s  %-12s", ownerId ? ownerId : "", 
               ownerDisplayName ? ownerDisplayName : "");
    }
    printf("\n");

    return S3StatusOK;
}

3.7 上傳對(duì)象回調(diào)函數(shù)

• 接口描述

1. 功能
   進(jìn)行上傳對(duì)象操作時(shí)的回調(diào)函數(shù)。

2. 定義

int (S3PutObjectDataCallback)(int bufferSize, char *buffer, void *callbackData);

3. 參數(shù)

示例代碼：

static int putObjectDataCallback(int bufferSize, char *buffer, void *callbackData)
{
    put_object_callback_data *data = 
        (put_object_callback_data *) callbackData;
    
    int ret = 0;

    if (data->contentLength) {
        int toRead = ((data->contentLength > (unsigned) bufferSize) ?
                      (unsigned) bufferSize : data->contentLength);
        if (data->gb) {
            growbuffer_read(&(data->gb), toRead, &ret, buffer);
        }
        else if (data->infile) {
            ret = fread(buffer, 1, toRead, data->infile);
        }
    }

    data->contentLength -= ret;

    if (data->contentLength && !data->noStatus) {
        // Avoid a weird bug in MingW, which won't print the second integer
        // value properly when it's in the same call, so print separately
        printf("%llu bytes remaining ", 
               (unsigned long long) data->contentLength);
        printf("(%d%% complete) ...\n",
               (int) (((data->originalContentLength - 
                        data->contentLength) * 100) /
                      data->originalContentLength));
    }

    return ret;
}

3.8 獲取對(duì)象回調(diào)函數(shù)

• 接口描述

1. 功能
   獲取對(duì)象時(shí)的回調(diào)函數(shù)。

2. 定義

S3Status (S3GetObjectDataCallback)(int bufferSize, const char *buffer, void *callbackData);

3. 參數(shù)

• 示例代碼

static S3Status getObjectDataCallback(int bufferSize, const char *buffer,
                                      void *callbackData)
{
    FILE *outfile = (FILE *) callbackData;

    size_t wrote = fwrite(buffer, 1, bufferSize, outfile);
    
    return ((wrote < (size_t) bufferSize) ? 
            S3StatusAbortedByCallback : S3StatusOK);
}

3.9 list bucket中對(duì)象回調(diào)函數(shù)

• 接口描述

1. 功能
   列舉bucket中對(duì)象時(shí)的回調(diào)函數(shù)。

2. 定義

S3Status (S3ListBucketCallback)(int isTruncated,
                                        const char *nextMarker,
                                        int contentsCount, 
                                        const S3ListBucketContent *contents,
                                        int commonPrefixesCount,
                                        const char **commonPrefixes,
                                        void *callbackData);

3. 參數(shù)

• 示例代碼

static S3Status listBucketCallback(int isTruncated, const char *nextMarker,
                                   int contentsCount, 
                                   const S3ListBucketContent *contents,
                                   int commonPrefixesCount,
                                   const char **commonPrefixes,
                                   void *callbackData)
{
    list_bucket_callback_data *data = 
        (list_bucket_callback_data *) callbackData;

    data->isTruncated = isTruncated;
    // This is tricky.  S3 doesn't return the NextMarker if there is no
    // delimiter.  Why, I don't know, since it's still useful for paging
    // through results.  We want NextMarker to be the last content in the
    // list, so set it to that if necessary.
    if ((!nextMarker||!nextMarker[0]) && contentsCount) {
        nextMarker = contents[contentsCount - 1].key;
    }
    if (nextMarker) {
        snprintf(data->nextMarker, sizeof(data->nextMarker), "%s", 
                 nextMarker);
    }
    else {
        data->nextMarker[0] = 0;
    }
    
    if (contentsCount && !data->keyCount) {
        printListBucketHeader(data->allDetails);
    }

    int i;
    for (i = 0; i < contentsCount; i++) {
        const S3ListBucketContent *content = &(contents[i]);
        char timebuf[256];
        if (0) {
            time_t t = (time_t) content->lastModified;
            strftime(timebuf, sizeof(timebuf), "%Y-%m-%dT%H:%M:%SZ",
                     gmtime(&t));
            printf("\nKey: %s\n", content->key);
            printf("Last Modified: %s\n", timebuf);
            printf("ETag: %s\n", content->eTag);
            printf("Size: %llu\n", (unsigned long long) content->size);
            if (content->ownerId) {
                printf("Owner ID: %s\n", content->ownerId);
            }
            if (content->ownerDisplayName) {
                printf("Owner Display Name: %s\n", content->ownerDisplayName);
            }
        }
        else {
            time_t t = (time_t) content->lastModified;
            strftime(timebuf, sizeof(timebuf), "%Y-%m-%dT%H:%M:%SZ", 
                     gmtime(&t));
            char sizebuf[16];
            if (content->size < 100000) {
                sprintf(sizebuf, "%5llu", (unsigned long long) content->size);
            }
            else if (content->size < (1024 * 1024)) {
                sprintf(sizebuf, "%4lluK", 
                        ((unsigned long long) content->size) / 1024ULL);
            }
            else if (content->size < (10 * 1024 * 1024)) {
                float f = content->size;
                f /= (1024 * 1024);
                sprintf(sizebuf, "%1.2fM", f);
            }
            else if (content->size < (1024 * 1024 * 1024)) {
                sprintf(sizebuf, "%4lluM", 
                        ((unsigned long long) content->size) / 
                        (1024ULL * 1024ULL));
            }
            else {
                float f = (content->size / 1024);
                f /= (1024 * 1024);
                sprintf(sizebuf, "%1.2fG", f);
            }
            printf("%-50s  %s  %s", content->key, timebuf, sizebuf);
            if (data->allDetails) {
                printf("  %-34s  %-64s  %-12s",
                       content->eTag, 
                       content->ownerId ? content->ownerId : "",
                       content->ownerDisplayName ? 
                       content->ownerDisplayName : "");
            }
            printf("\n");
        }
    }

    data->keyCount += contentsCount;

    for (i = 0; i < commonPrefixesCount; i++) {
        printf("\nCommon Prefix: %s\n", commonPrefixes[i]);
    }

    return S3StatusOK;
}

四 bucket操作

4.1 test bucket

• 接口描述

1. 功能
   檢查bucket是否存在，如果存在則返回bucket的location。

2. 定義

void S3_test_bucket(S3Protocol protocol, S3UriStyle uriStyle,
                    const char *accessKeyId, const char *secretAccessKey,
                    const char *hostName, const char *bucketName,
                    int locationConstraintReturnSize,
                    char *locationConstraintReturn,
                    S3RequestContext *requestContext,
                    const S3ResponseHandler *handler, void *callbackData);

3. 參數(shù)

4.2 create bucket

• 接口描述

1. 功能
   創(chuàng)建bucket。

2. 定義

void S3_create_bucket(S3Protocol protocol, const char *accessKeyId,
                      const char *secretAccessKey, const char *hostName,
                      const char *bucketName, S3CannedAcl cannedAcl,
                      const char *locationConstraint,
                      S3RequestContext *requestContext,
                      const S3ResponseHandler *handler, void *callbackData);

3. 參數(shù)

4.3 delete bucket

• 接口描述

1. 功能
   刪除一個(gè)已經(jīng)存在的bucket。
   *必須是空bucket才能刪除

2. 定義

void S3_delete_bucket(S3Protocol protocol, S3UriStyle uriStyle,
                      const char \*accessKeyId, const char \*secretAccessKey,
                      const char \*hostName, const char \*bucketName,
                      S3RequestContext \*requestContext,
                      const S3ResponseHandler \*handler, void \*callbackData);

3. 參數(shù)

4.4 list bucket

• 接口描述

1. 功能
   列舉bucket中所有的對(duì)象。

2. 定義

void S3_list_bucket(const S3BucketContext \*bucketContext,
                    const char \*prefix, const char \*marker, 
                    const char \*delimiter, int maxkeys,
                    S3RequestContext \*requestContext,
                    const S3ListBucketHandler \*handler, void \*callbackData);

3. 參數(shù)

五 object操作

5.1 put object

• 接口描述

1. 功能
   上傳對(duì)象。

2. 定義

void S3_put_object(const S3BucketContext \*bucketContext, const char \*key,
                   uint64_t contentLength,
                   const S3PutProperties \*putProperties,
                   S3RequestContext \*requestContext,
                   const S3PutObjectHandler \*handler, void \*callbackData);

3. 參數(shù)

5.2 copy object

• 接口描述

1. 功能
   拷貝對(duì)象到目標(biāo)桶并命名。

2. 定義

void S3_copy_object(const S3BucketContext \*bucketContext,
                    const char \*key, const char \*destinationBucket,
                    const char \*destinationKey,
                    const S3PutProperties \*putProperties,
                    int64_t \*lastModifiedReturn, int eTagReturnSize,
                    char \*eTagReturn, S3RequestContext \*requestContext,
                    const S3ResponseHandler \*handler, void \*callbackData);

3. 參數(shù)

5.3 get object

• 接口描述

1. 功能
   下載對(duì)象。
2. 定義

void S3_get_object(const S3BucketContext \*bucketContext, const char \*key,
                   const S3GetConditions \*getConditions,
                   uint64_t startByte, uint64_t byteCount,
                   S3RequestContext \*requestContext,
                   const S3GetObjectHandler \*handler, void \*callbackData);

3. 參數(shù)

5.4 head object

• 接口描述

1. 功能
   獲取對(duì)象的屬性值。

2. 定義

void S3_head_object(const S3BucketContext \*bucketContext, const char \*key,
                    S3RequestContext \*requestContext,
                    const S3ResponseHandler \*handler, void \*callbackData);

3. 參數(shù)

5.5 delete object

• 接口描述

1. 功能
   刪除對(duì)象。

2. 定義

void S3_delete_object(const S3BucketContext \*bucketContext, const char \*key,
                      S3RequestContext \*requestContext,
                      const S3ResponseHandler \*handler, void \*callbackData);

3. 參數(shù)

六 訪問(wèn)控制列表操作

6.1 get acl

• 接口描述

1. 功能
   獲取bucket或object的訪問(wèn)控制權(quán)限。

2. 定義

void S3_get_acl(const S3BucketContext \*bucketContext, const char \*key, 
                char \*ownerId, char \*ownerDisplayName,
                int \*aclGrantCountReturn, S3AclGrant \*aclGrants, 
                S3RequestContext \*requestContext,
                const S3ResponseHandler \*handler, void \*callbackData);

3. 參數(shù)

6.2 set acl

• 接口描述

1. 功能
   設(shè)置bucket或object的權(quán)限。

2. 定義

void S3_set_acl(const S3BucketContext \*bucketContext, const char \*key, 
                const char \*ownerId, const char \*ownerDisplayName,
                int aclGrantCount, const S3AclGrant \*aclGrants, 
                S3RequestContext \*requestContext,
                const S3ResponseHandler \*handler, void \*callbackData);

3. 參數(shù)

七 服務(wù)訪問(wèn)日志管理

7.1 get_server_access_logging

• 接口描述

1. 功能
   獲取一個(gè)bucket的服務(wù)訪問(wèn)日志配置。

2. 定義

void S3_get_server_access_logging(const S3BucketContext \*bucketContext,
                                  char \*targetBucketReturn,
                                  char \*targetPrefixReturn,
                                  int \*aclGrantCountReturn, 
                                  S3AclGrant \*aclGrants,
                                  S3RequestContext \*requestContext,
                                  const S3ResponseHandler \*handler,
                                  void \*callbackData);

3. 參數(shù)

7.2 set_server_access_logging

• 接口描述

1. 功能
   設(shè)置一個(gè)bucket的服務(wù)訪問(wèn)日志配置。

2. 定義

void S3_set_server_access_logging(const S3BucketContext \*bucketContext,
                                  const char \*targetBucket, 
                                  const char \*targetPrefix, int aclGrantCount, 
                                  const S3AclGrant \*aclGrants, 
                                  S3RequestContext \*requestContext,
                                  const S3ResponseHandler \*handler,
                                  void \*callbackData);

3. 參數(shù)