閱讀879 返回首頁    go 網易 go 網易蜂巢

對象存儲 GOLANG SDK

目錄

安裝

SDK

Git hub地址: https://github.com/NetEase-Object-Storage/nos-golang-sdk
曆史版本: 無

環境要求

建議golang 1.3+ 使用以下命令顯示當前的golang版本:

go version

安裝

命令行方式

在命令行下執行： 

go get -u github.com/NetEase-Object-Storage/nos-golang-sdk

sdk會安裝到GOPATH目錄下

源碼安裝

從git hub地址上手動下載sdk，存到GOPATH目錄下。使用以下命令顯示當前的GOPATH路徑: 

go env

初始化

確定EndPoint

EndPoint 是NOS各個區域的地址，目前支持以下形式

EndPoint類型 備注
NOS區域域名地址 使用桶所在的區域的NOS域名地址

NOS區域域名地址

進入NOS控製台，在桶的 屬性 中可以查找到當前桶所在的區域及域名，桶的域名的後綴部分為 該桶的公網域名，例如:test-logging.nos-eastchina1.126.net中的nos-eastchina1.126.net 為該桶的公網EndPoint。

配置秘鑰

要接入NOS服務，您需要一對有效的AccessKey（包括AccessKeyId與AccessKeySecret）來進行 簽名驗證，開通服務與AccessKey請參考 訪問控製 :

在獲取到AccessKeyId與AccessKeySecret之後，可以按照以下的步驟進行初始化

新建NosClient

GO-SDK提供的接口都在NosClient中實現，並以成員方法的方式對外提供調用。因此使用GO-SDK前必須實例化一個NosClient對象。

關於請求參數

NosClient中的方法采用對象方式進行傳參： 

package main

 import (
    "fmt"

    "github.com/NetEase-Object-Storage/nos-golang-sdk/nosclient"
    "github.com/NetEase-Object-Storage/nos-golang-sdk/model"
 )

func main() {
    copyObjectRequest := &CopyObjectRequest{
        SrcBucket : TEST_BUCKET,
        SrcObject : PUTOBJECTFILE,
        DestBucket : TEST_BUCKET,
        DestObject : "CopiedTest",
    }
    err := nosClient.CopyObject(copyObjectRequest)
}

實例化NosClient

如果您需要修改NosClient的默認參數，可以在實例化NosClient時傳入Config實例。Config是NosClient的配置類，可配置連接超時、Key等參數。通過Config可以設置的參數見下表：

參數 描述 是否必須
Endpoint 上傳的NOS地址 是
AccessKey 認證使用的Access Key 否
SecretKey 認證使用的Access Secret 否
NosServiceConnectTimeout 建立連接的超時時間（單位：秒）默認：30秒 否
NosServiceReadWriteTimeout Socket層傳輸數據超時時間（單位：秒）默認：60秒 否
NosServiceMaxIdleConnection 最大空閑連接時間（單位：秒）默認：60秒 否
LogLevel 打印日誌的等級默認：Debug 否
Logger 打印日誌的對象 否

帶Config參數實例化NosClient的示例代碼： 

package main

  import (
     "fmt"

     "github.com/NetEase-Object-Storage/nos-golang-sdk/nosclient"
     "github.com/NetEase-Object-Storage/nos-golang-sdk/model"
     "github.com/NetEase-Object-Storage/nos-golang-sdk/logger"
  )

 func main() {
     conf := &config.Config{
         Endpoint:  "nos.netease.com",
         AccessKey: "your-accesskey",
         SecretKey: "your-secretkey",

         NosServiceConnectTimeout:    3,
         NosServiceReadWriteTimeout:  15,
         NosServiceMaxIdleConnection: 500,

         LogLevel:  logger.LogLevel(logger.DEBUG),
         Logger:    logger.NewDefaultLogger(),

     }

     nosClient, err := nosclient.New(conf)
     if err != nil {
         fmt.Println(err.ERROR())
         return
     }
}

Attention: 

 1. 後麵的示例代碼默認您已經實例化了所需的NosClient對象, 不再贅述,後續的代碼示例均需要將實例化的代碼寫入main函數

快速入門

快速入門

請確認您已經熟悉NOS的基本概念，如Bucket、Object、EndPoint、AccessKeyId和AccessKeySecret等。 本節您將看到如何快速的使用NOS GOLANG SDK,完成常用的操作，上傳文件、下載文件等

常用包

常用類型 備注
nosclient 包含了主要的對象操作API
model 包含了對象操作API的請求和響應的結構類型

基本操作

上傳文件

對象（Object）是NOS中最基本的數據單元，您可以把它簡單的理解為文件，以下代碼可以實現簡單的對象上傳: 

  package main

  import (
     "fmt"

     "github.com/NetEase-Object-Storage/nos-golang-sdk/nosclient"
     "github.com/NetEase-Object-Storage/nos-golang-sdk/model"
  )

 func main() {

     metadata := &model.ObjectMetadata{
             Metadata: map[string]string{
                  nosconst.CONTENT_TYPE:     contentType,
                  nosconst.CONTENT_MD5:      OBJECTMD5,
             },
     }

     putObjectRequest := &model.PutObjectRequest{
             Bucket:   "使用的桶名，注意命名規則",
             Object:   "使用的對象名，注意命名規則",
             FilePath: path,
             Metadata: metadata,
     }

     result, err := nosClient.PutObjectByFile(putObjectRequest)
     if err != nil {
             fmt.Println(err.Error())  // Message from an error.
     } else {
             fmt.Println(result) // Pretty-print the response data.
     }
}

Attention: 

 1. 對象命名規則請參見 API 手冊 對象

更多的上傳文件信息，請參見 NOS-GOLANG-SDK 上傳文件

下載文件

上傳對象成功之後，您可以讀取它的內容，以下代碼可以實現文件的下載: 

package main
import (
    "fmt"

    "github.com/NetEase-Object-Storage/nos-golang-sdk/nosclient"
    "github.com/NetEase-Object-Storage/nos-golang-sdk/model"
)

func main() {
     objectRequest := &model.GetObjectRequest{
            Bucket:         "使用的桶名，注意命名規則",
            Object:         "使用的對象名，注意命名規則",
    }
    objectResult, err := nosClient.GetObject(objectRequest)
    if err != nil {
            fmt.Println(err.Error())
    }
}

更多的下載文件信息，請參見 NOS-GOLANG-SDK 下載文件

列舉文件

當上傳文件成功之後，可以查看桶中包含的文件列表，以下代碼展示如何列舉桶內的文件: 

package main
import (
    "fmt"

    "github.com/NetEase-Object-Storage/nos-golang-sdk/nosclient"
    "github.com/NetEase-Object-Storage/nos-golang-sdk/model"
)

func main() {
    listRequest := &model.ListObjectsRequest{
            Bucket:    "使用的桶名，注意命名規則",
            Prefix:    PREFIX,
            Delimiter: DELIMITER,
            Marker:    MARKER,
            MaxKeys:   100,
    }
    objectResult, err := s.nosClient.ListObjects(listRequest)
    if err != nil {
            fmt.Println(err.Error())
    }
}

Note: 

 1. 上麵的代碼默認列舉100個object

更多的管理文件信息，請參見 NOS-GOLANG-SDK 文件管理

刪除文件

文件上傳成功後，可以指定刪除桶中的文件，以下代碼實現桶中文件的刪除: 

package main
import (
    "fmt"

    "github.com/NetEase-Object-Storage/nos-golang-sdk/nosclient"
    "github.com/NetEase-Object-Storage/nos-golang-sdk/model"
)

func main() {
    objectRequest := &model.ObjectRequest{
         Bucket : "使用的桶名，注意命名規則",
         Object : "使用的對象名，注意命名規則",
    }

    err := nosClient.DeleteObject(objectRequest)
    if err != nil {
        fmt.Println(err.Error())  // Message from an error.
        return
    }
}

文件上傳

在NOS中用戶的基本操作單元是對象，亦可以理解為文件，NOS PHP SDK提供了豐富的上傳接口，可以通過以下的方式上傳文件: 

 1. 流式上傳
 2. 本地文件上傳
 3. 大對象上傳

字符串上傳、本地文件上傳最大為100M，大對象上傳對文件大小沒有限製

流式上傳

通過PutObjectByStream方法上傳對象，該方法隻支持小於100M的對象。示例代碼如下： 

package main

import (
    "fmt"
    "os"

    "github.com/NetEase-Object-Storage/nos-golang-sdk/nosclient"
    "github.com/NetEase-Object-Storage/nos-golang-sdk/model"
    "github.com/NetEase-Object-Storage/nos-golang-sdk/nosconst"
)

func main() {

    file, err := os.Open(Path)

    metadata := &model.ObjectMetadata{
            ContentLength: contentLength,
            Metadata: map[string]string{
                  nosconst.CONTENT_TYPE:     CONTENTTYPE,
                  nosconst.CONTENT_MD5:      OBJECTMD5,
            },
    }

    putObjectRequest := &model.PutObjectRequest{
            Bucket:   "使用的桶名，注意命名規則",
            Object:   "使用的對象名，注意命名規則",
            Body:     file,
            Metadata: metadata,
    }

    result, err := nosClient.PutObjectByStream(putObjectRequest)
    if err != nil {
            fmt.Println(err.Error())  // Message from an error.
    } else {
            fmt.Println(result) // Pretty-print the response data.
    }
}

Attention: 

 1. 上傳的字符串內容不超過100M

本地文件上傳

通過PutObjectByFile方法上傳本地文件，該方法隻支持小於100M的文件。示例代碼如下： 

package main

  import (
     "fmt"

     "github.com/NetEase-Object-Storage/nos-golang-sdk/nosclient"
     "github.com/NetEase-Object-Storage/nos-golang-sdk/model"
  )

 func main() {

     metadata := &model.ObjectMetadata{
             Metadata: map[string]string{
                  nosconst.CONTENT_TYPE:     contentType,
                  nosconst.CONTENT_MD5:      OBJECTMD5,
             },
     }

     putObjectRequest := &model.PutObjectRequest{
             Bucket:   "使用的桶名，注意命名規則",
             Object:   "使用的對象名，注意命名規則",
             FilePath: path,
             Metadata: metadata,
     }

     result, err := nosClient.PutObjectByFile(putObjectRequest)
     if err != nil {
             fmt.Println(err.Error())  // Message from an error.
     } else {
             fmt.Println(result) // Pretty-print the response data.
     }
}

Attention: 

 1. 上傳的文件內容不超過100M

分片上傳

除了通過putObject接口上傳文件到NOS之外，NOS還提供了另外一種上傳模式-分片上傳,用戶可以在如下應用場景內（但不限於此），使用分片上傳模式，如： 

 1. 需支持斷點上傳
 2. 上傳超過100M的文件
 3. 網絡條件較差，經常和NOS服務器斷開連接
 4. 上傳前無法確定文件大小

初始化分塊

通過InitMultiUpload方法實現分塊上傳的初始化。示例代碼如下： 

package main

import (
    "fmt"

    "github.com/NetEase-Object-Storage/nos-golang-sdk/nosclient"
    "github.com/NetEase-Object-Storage/nos-golang-sdk/model"
)

func main() {
    initRequest := &model.InitMultiUploadRequest{
            Bucket:   "使用的桶名，注意命名規則",
            Object:   "使用的對象名，注意命名規則",
    }

    initResult, err := nosClient.InitMultiUpload(initRequest)
    if err != nil {
            fmt.Println(err.Error())
    }

    uploadId := initResult.UploadId      //同一個對象的分塊上傳都要攜帶該uploadId
}

分塊上傳

通過UploadPart方法實現分塊上傳。示例代碼如下： 

package main

import (
    "os"

    "github.com/NetEase-Object-Storage/nos-golang-sdk/nosclient"
    "github.com/NetEase-Object-Storage/nos-golang-sdk/model"
)

func main() {
        file, err := os.Open(path)
        uploadPartRequest := &model.UploadPartRequest{
            Bucket:     "使用的桶名，注意命名規則",
            Object:     "使用的對象名，注意命名規則",
            UploadId:   uploadId,
            PartNumber: partNumber,      //number of uploading
            Content:    content,         //content of uploading
            PartSize:   partSize,        //size of uploading the part
            ContentMd5: OBJECTMD5,       //md5 of uploading the part
        }
        buffer := make([]byte, BufferSize)
        var partNum int
        for ; ;  {
            partNum++
            readLen, err := file.Read(buffer)
            if err != nil || n == 0 {
                break
            }

            uploadPartRequest.PartSize = int64(readLen)
            uploadPartRequest.PartNumber = partNum
            uploadPartRequest.Content = buffer
            uploadPart, err := nosClient.UploadPart(uploadPartRequest)
            if err != nil {
                break
            }
       }
}

分塊終止上傳

通過AbortMultiUpload方法終止分塊上傳。示例代碼如下： 

package main

import (
    "fmt"

    "github.com/NetEase-Object-Storage/nos-golang-sdk/nosclient"
    "github.com/NetEase-Object-Storage/nos-golang-sdk/model"
)

func main() {
    abortMultiUploadRequest := &model.AbortMultiUploadRequest{
            Bucket:             "使用的桶名，注意命名規則",
            Object:             "使用的對象名，注意命名規則",
            UploadId:           uploadId,
    }
    err := nosClient.AbortMultiUpload(abortMultiUploadRequest)
    if err != nil {
            fmt.Println(err.Error())
    }
}

完成分塊上傳

通過CompleteMultiUpload方法完成分塊上傳。示例代碼如下： 

package main

import (
    "fmt"

    "github.com/NetEase-Object-Storage/nos-golang-sdk/nosclient"
    "github.com/NetEase-Object-Storage/nos-golang-sdk/model"
)

func main() {
    completeMultiUploadRequest := &model.CompleteMultiUploadRequest{
            Bucket:     "使用的桶名，注意命名規則",
            Object:     "使用的對象名，注意命名規則",
            UploadId:   uploadId,
            Parts:      etags,       //map，partnum: etag
            ContentMd5: contentMd5,  //body md5
            ObjectMd5:  objectMd5,   //big file md5
    }
    completeResult, err := nosClient.CompleteMultiUpload(completeMultiUploadRequest)
    if err != nil {
            fmt.Println(err.Error())
    }
}

列出分塊

查看已經上傳的分片可以羅列出指定Upload ID(InitiateMultipartUpload時獲取)所屬的所有已經上傳成功的分片，您可以通過NosClient::listParts接口獲取已經上傳的分片，可以參考以下代碼:

通過ListUploadParts方法實現列出一個UploadId對應的所有分塊。可以設置的參數為：

參數 作用
UploadId 分塊上傳的UploadId
MaxParts 響應中的limit個數, 取值範圍[0-1000]，默認1000
PartNumberMarker 分塊號的界限，隻有更大的分塊號會被列出來

示例代碼如下： 

 package main
 import (
     "fmt"

     "github.com/NetEase-Object-Storage/nos-golang-sdk/nosclient"
     "github.com/NetEase-Object-Storage/nos-golang-sdk/model"
 )

 func main() {
     listUploadPartsRequest := &model.ListUploadPartsRequest{
             Bucket:           "使用的桶名，注意命名規則",
             Object:           "使用的對象名，注意命名規則",
             UploadId:         uploadId,
             MaxParts:         2,
             PartNumberMarker: 20,
     }
     completeResult, err := nosClient.ListUploadParts(completeMultiUploadRequest)
     if err != nil {
             fmt.Println(err.Error())
     }
}

列出所有上傳的分塊

通過ListMultiUploads方法羅列出所有執行中的Multipart Upload事件，即已經被初始化的Multipart Upload但是未被Complete或者Abort的Multipart Upload事件。可以設置的參數為：

參數 作用
KeyMarker 指定某一uploads key，隻有大於該key-marker的才會被列出
MaxUploads 最多返回max-uploads條記錄，取值範圍[0-1000]，默認1000

示例代碼如下： 

package main
import (
    "fmt"

    "github.com/NetEase-Object-Storage/nos-golang-sdk/nosclient"
    "github.com/NetEase-Object-Storage/nos-golang-sdk/model"
)

func main() {
    listMultiUploadsRequest = &model.ListMultiUploadsRequest{
            Bucket:     "使用的桶名，注意命名規則",
            KeyMarker:  KEYMARKER,
            MaxUploads: 20,
    }
    completeResult, err := nosClient.ListMultiUploads(listMultiUploadsRequest)
    if err != nil {
            fmt.Println(err.Error())
    }
}

文件下載

下載文件

通過GetObject方法獲取對象的網絡流。可以設置的參數列表為：

參數 作用
ObjRange 下載指定對象的指定範圍的數據
IfModifiedSince 文件的最後修改時間小於等於If-Modified-Since參數指定的時間，則不進行下載，否則正常下載文件

示例代碼如下： 

package main
import (
    "fmt"

    "github.com/NetEase-Object-Storage/nos-golang-sdk/nosclient"
    "github.com/NetEase-Object-Storage/nos-golang-sdk/model"
)

func main() {
     objectRequest := &model.GetObjectRequest{
            Bucket:         "使用的桶名，注意命名規則",
            Object:         "使用的對象名，注意命名規則",
    }
    objectResult, err := nosClient.GetObject(objectRequest)
    if err != nil {
            fmt.Println(err.Error())
    }
}

文件管理

在NOS中，用戶可以通過一係列的接口管理桶(Bucket)中的文件(Object)，比如ListObjects，DeleteObject，CopyObject，DoesObjectExist等。

列出桶中的文件

通過ListObjects方法獲取用戶桶下麵的對象。可以設置的參數列表如下：

參數 作用
Prefix 限定返回的object key必須以prefix作為前綴
Delimiter 是一個用於對Object名字進行分組的字符。所有名字包含指定的前綴且第一次出現delimiter字符之間的object作為一組元素——CommonPrefixes
Marker 字典序的起始標記，隻列出該標記之後的部分
MaxKeys 限定返回的數量，返回的結果小於或等於該值(默認值為100)

示例代碼如下： 

package main
import (
    "fmt"

    "github.com/NetEase-Object-Storage/nos-golang-sdk/nosclient"
    "github.com/NetEase-Object-Storage/nos-golang-sdk/model"
)

func main() {
    listRequest := &model.ListObjectsRequest{
            Bucket:    "使用的桶名，注意命名規則",
            Prefix:    PREFIX,
            Delimiter: DELIMITER,
            Marker:    MARKER,
            MaxKeys:   100,
    }
    objectResult, err := nosClient.ListObjects(listRequest)
    if err != nil {
            fmt.Println(err.Error())
    }
}

判斷文件是否存在

通過DoesObjectExist方法來判斷對象是否存在。示例代碼如下： 

package main
 import (
     "fmt"

     "github.com/NetEase-Object-Storage/nos-golang-sdk/nosclient"
     "github.com/NetEase-Object-Storage/nos-golang-sdk/model"
 )

 func main() {
     objectRequest := &model.ObjectRequest{
             Bucket : "使用的桶名，注意命名規則",
             Object : "使用的對象名，注意命名規則",
     }

     isExist, err := nosClient.DoesObjectExist(objectRequest)
     if err != nil {
             fmt.Println(err.Error())  // Message from an error.
     }
}

刪除單個文件

通過DeleteObject方法實現單個文件刪除功能。示例代碼如下: 

package main
import (
    "fmt"

    "github.com/NetEase-Object-Storage/nos-golang-sdk/nosclient"
    "github.com/NetEase-Object-Storage/nos-golang-sdk/model"
)

func main() {
    objectRequest := &model.ObjectRequest{
         Bucket : "使用的桶名，注意命名規則",
         Object : "使用的對象名，注意命名規則",
    }

    err := nosClient.DeleteObject(objectRequest)
    if err != nil {
        fmt.Println(err.Error())  // Message from an error.
        return
    }
}

刪除多個文件

通過DeleteMultiObjects方法實現多個文件刪除功能。示例代碼如下： 

package main
import (
    "fmt"

    "github.com/NetEase-Object-Storage/nos-golang-sdk/nosclient"
    "github.com/NetEase-Object-Storage/nos-golang-sdk/model"
)

func main() {
    deleteMultiObjects := DeleteMultiObjects{
            Quiet: false,            //詳細和靜默模式，設置為true的時候，隻返回刪除錯誤的文件列表，設置為false的時候，成功和失敗的文件列表都返回
    }
    deleteMultiObjects.Append(DeleteObject{Key:PUTOBJECTFILE})
    deleteMultiObjects.Append(DeleteObject{Key:PUTOBJECTFILE+"1"})
    deleteMultiObjects.Append(DeleteObject{Key:PUTOBJECTFILE+"2"})
    deleteMultiObjects.Append(DeleteObject{Key:PUTOBJECTFILE+"3"})

    deleteRequest := &DeleteMultiObjectsRequest{
            Bucket : "使用的桶名，注意命名規則",
            DelectObjects : &deleteMultiObjects,
    }
    deleteResult, err := nosClient.DeleteMultiObjects(deleteRequest)
    if err != nil {
            fmt.Println(err.Error())
    }
}

拷貝文件

通過CopyObject方法實現對象複製功能，NOS支持桶內copy以及相同用戶的跨桶copy。示例代碼如下： 

package main
import (
    "fmt"

    "github.com/NetEase-Object-Storage/nos-golang-sdk/nosclient"
    "github.com/NetEase-Object-Storage/nos-golang-sdk/model"
)

func main() {
    copyRequest := &model.CopyObjectRequest{
        SrcBucket :  SRC_BUCKET,
        SrcObject :  SRC_OBJECT,
        DestBucket : DEST_BUCKET,
        DestObject : DEST_OBJECT,
    }

    err := nosClient.CopyObject(copyRequest)
    if err != nil {
        fmt.Println(err.Error())  // Message from an error
    }
}

Attention: 

 1 .支持跨桶的文件copy

移動文件

通過MoveObject方法實現對象重命名，NOS隻支持桶內重命名。示例代碼如下： 

package main
import (
    "fmt"

    "github.com/NetEase-Object-Storage/nos-golang-sdk/nosclient"
    "github.com/NetEase-Object-Storage/nos-golang-sdk/model"
)

func main() {
    moveRequest := &model.MoveObjectRequest{
            SrcBucket :  SRC_BUCKET,
            SrcObject :  SRC_OBJECT,
            DestBucket : DEST_BUCKET,
            DestObject : DEST_OBJECT,
    }

    err := nosClient.MoveObject(moveRequest)
    if err != nil {
            fmt.Println(err.Error())  // Message from an error.
    }
}

Attention: 

 1.暫時不支持跨桶的文件move

獲取文件的文件元信息

通過GetObjectMetaData方法獲取文件的元數據。示例代碼如下： 

package main
import (
    "fmt"

    "github.com/NetEase-Object-Storage/nos-golang-sdk/nosclient"
    "github.com/NetEase-Object-Storage/nos-golang-sdk/model"
)

func main() {
    objectRequest := &model.GetObjectRequest{
            Bucket:         "使用的桶名，注意命名規則",
            Object:         "使用的對象名，注意命名規則",
    }
    metaData, err := nosClient.GetObjectMetaData(objectRequest)
    if err != nil {
            fmt.Println(err.Error())
    }
}

錯誤處理

返回的錯誤類型一共有兩種，分別是客戶端錯誤和服務端錯誤，分別都實現了error方法。 

type ClientError struct {
    StatusCode int
    Resource string
    Message  string
}

type ServerError struct {
    StatusCode int
    RequestId  string
    NosErr     NosError   //服務端返回的原始錯誤內容
}

type NosError struct {
    Code         string
    Message      string
    Resource     string
    NosRequestId string  //請求ID,非常重要，有利於nos開發人員跟蹤異常請求的錯誤原因
}
Next  Previous

最後更新：2017-01-03 10:48:53

  上一篇：go 創建容器
  下一篇：go 數據中心和域名