[教程]ChainSafe Storage使用教程

ChainSafe Storage是一套API和服務,允許用戶從IPFS和Filecoin存儲和檢索數據。

概述

鏈安全存儲的 API 規範。

您可以在 https://storage.chainsafe.io 找到有關鏈安全存儲的更多信息。

Buckets

以下 API 規範使用Buckets的概念進行操作。它在概念上類似於使用相同術語的其他存儲服務中的功能。Buckets表示一種文件分組機製,該機製允許屬於Buckets的所有文件成為元數據層次結構的一部分。這幾乎類似於文件系統,但沒有每個文件的訪問控製,而是在每個Buckets級別控製訪問。

上傳到IPFS的所有文件都以扁平結構表示,但像這樣存儲它們是不夠的,因此顯而易見的想法是使用IPFS文件系統。但是,這樣的文件系統對所有人開放,可能會顯示文件或文件夾名稱以及相對位置,這可能是用戶可能永遠不想透露的內容。作為這個問題的解決方案,我們以一種不會向公共網絡上的任何人透露的方式存儲文件的層次結構,它基本上將存儲為IPFS對象。

與IPFS的扁平結構不同,我們的文件系統將保留原始文件名,相對路徑,內容類型,大小,最重要的是在此元數據和實際IPFS CIDv0之間創建映射。

如前所述,我們不是對文件進行訪問控製檢查(因為考慮到IPFS的性質是不可能的),而是對文件系統和Bucket進行訪問控製檢查。因此,只有具有適當訪問權限的用戶才能管理特定存儲桶中的數據,從而對底層文件系統進行更改,並發現上傳文件的元數據和 CID 之間的映射。

對我們來說,僅使用內部文件系統是不公平的,因此也可以創建一個與IPFS文件系統關聯的存儲桶。

總結我們剛剛描述的所有內容,Buckets 是一個包含的結構:

文件系統(文件層次結構)類型:或一種chainsafeipfs

列表或所有者、作者、讀者

與其關聯的所有數據的大小

更正式的定義可以在下面的規範中找到:

S3 兼容性

Chainsafe Storage在使用IPFS的分布式存儲之上提供S3兼容層。存儲 S3 API 可以使用任何可用的 S3 客戶端輕松與您的服務集成。

如果您目前不是Chainsafe Storage用戶,您可以立即創建一個帳戶並獲得20 GB的免費存儲空間。

認證

鏈安全存儲 S3 兼容 API 僅支持 v4 簽名進行身份驗證。它們目前不支持 v2 簽名。

創建訪問密鑰 ID 和秘密訪問密鑰

要獲取密鑰,您可以登錄鏈安全存儲 Web UI

轉到「設置」部分:

通過單擊「添加 S3 密鑰」發出密鑰對:

註意:請確保保存密鑰,因為它不會再次顯示。

通過用戶 API 創建訪問密鑰

POST /api/v1/user/keys HTTP/1.1
Host: https://api.chainsafe.io
Authorization: Bearer <AUTH_TOKEN>
Content-Type: application/json
{
“type” : “storage”
}

響應:(內容類型: application/json )

{
“id”: “YQIGFGKQAHMJCTPEEHXJ”,
“created_at”: “2022-09-05T17:48:53.290381647Z”,
“status”: “active”,
“type”: “s3”,
“secret”: “zOdKnLzZQ9gzaCFTbxiomgZbMJi6I1pTIuJ81PEK”
}

您可以創建或鍵入 api 密鑰。 storage s3

開發工具包

與鏈安全存儲 S3 兼容的 API 可與現有的 AWS 開發工具包一起使用。有關如何配置 AWS 開發工具包的指南,請參閱:

支持的功能

與存儲 S3 兼容的 API 以與 AWS S3 相同的方式返回響應。以下是存儲 S3 兼容 API 支持的功能

  • Create Bucket
  • Copy Object
  • Delete Bucket
  • Delete Object
  • Get Object
  • Head Bucket
  • Head Object
  • List Bucket
  • List Objects V2
  • Put Object

AWS S3 命令行界面指南

AWS S3 CLI 是與對象存儲交互的最簡單方法。AWS S3 CLI 可以配置為利用 Chainsafe Storage S3 Compatible API。

配置 AWS S3 CLI

1.在 AWS 憑證文件中為鏈安全存儲創建新的配置文件

   $ vi ~/.aws/credentials
   [storage]
   aws_access_key_id = xxx
   aws_secret_access_key = xxx

2.現在,使用上面創建的存儲配置文件,並通過向 AWS S3 CLI 提供自定義終端節點(鏈安全存儲)與鏈安全存儲 S3 兼容 API 進行交互

   $ aws s3 mb s3://storage-s3-test --endpoint-url https://buckets.chainsafe.io --profile storage
   make_bucket: storage-s3-test

   $ aws s3 ls --endpoint-url https://buckets.chainsafe.io --profile storage
   2022-05-11 14:36:46 storage-s3-test

戈朗指南
本指南向您展示如何使用 Go 集成 S3 兼容存儲層。

在繼續之前,請確保您擁有上述存儲 S3 密鑰。

我們將使用 minio S3 客戶端進行 Go。

操作:
製作 Buckets
讓我們創建一個要啟動的 Buckets。

func main() {
serviceAddress := “buckets.storage.io

 // pass in your S3 key id and secret here.
 accessKey, secKey := "", ""

 // initiate the minio client
 client, err := minio.New(serviceAddress, &minio.Options{
     Creds:  credentials.NewStaticV4(accessKey, secKey, ""),
     Region: "us-east-1", // make sure to set it
     Secure: true,
 })
 if err != nil {
    log.Panic(err)
 }

 // bucket name to be created
 bucketName := "test-bucket"

 // create bucket
 ctx := context.Background()
 err = client.MakeBucket(ctx, bucketName, minio.MakeBucketOptions{})
 if err != nil {
    log.Panicf("error creating bucket \"%s\": %s", bucketName, err.Error())
 }

}
列出 Buckets
現在,我們將列出在上一步中創建的存儲桶。

func main() {
ctx := context.Background()

    // list buckets
    buckets, err := client.ListBuckets(ctx)
    if err != nil {
        log.Panicf("error list buckets: %s", err.Error())
    }

    for _, b := range buckets {
        log.Printf("i have \"%s\" bucket\n", b.Name)
    }
}

上傳對象
我們將對象上傳到上面創建的 Buckets。

func main() {
ctx := context.Background()

 // bucket name that we created
 bucketName := "test-bucket"

 // present working directory
 pwd, err := os.Getwd()
 if err != nil {
     log.Panicf("can't get PWD: %s", err)
 }

 // document paths
 myDocument1 := filepath.Join(pwd, "document1.pdf")

 // S3 path keys
 document1Key := "letter1/document.pdf"

 // upload objects to the bucket
 _, err = client.FPutObject(
     ctx, bucketName, document1Key, myDocument1, minio.PutObjectOptions{
         DisableMultipart: true,
     })
 if err != nil {
     log.Panicf("error putting object \"%s\" to bucket: %s", myDocument1, err.Error())
 }

}
獲取對象
我們將列出我們在上一步中添加到 Buckets的對象。

func main() {
ctx := context.Background()

 // bucket name that we created
 bucketName := "test-bucket"

 // S3 path key
 document1Key := "letter1/document.pdf"

 // get objects
 _, err = client.GetObject(ctx, bucketName, document1Key, minio.GetObjectOptions{})
 if err != nil {
     log.Panicf("error getting the object itself: %s", err.Error())
 }

}
列出對象
We will not list all the files in the bucket with different options.

func main() {
ctx := context.Background()

 // bucket name that we created
 bucketName := "test-bucket"

 // list files by full paths
 objListOptions := minio.ListObjectsOptions{Prefix: "/", Recursive: true}
 for object := range client.ListObjects(ctx, bucketName, objListOptions) {
     log.Printf("recursive on root object: %s\n", object.Key)
 }

 // list root directories
 objListOptions = minio.ListObjectsOptions{Prefix: "/", Recursive: false}
 for object := range client.ListObjects(ctx, bucketName, objListOptions) {
     log.Printf("non-recursive on root object: %s\n", object.Key)
 }

 // list files in folder `/letter1`
 objListOptions = minio.ListObjectsOptions{Prefix: "/letter1", Recursive: true}
 for object := range client.ListObjects(ctx, bucketName, objListOptions) {
     log.Printf("recursive on subfolder object: %s\n", object.Key)
 }

}
檢查 Buckets是否存在
func main() {
ctx := context.Background()

 // bucket name that we created
 bucketName := "test-bucket"

 exists, err := client.BucketExists(ctx, bucketName)
 if err != nil {
   log.Panicf("error checking bucket existense \"%s\": %s", bucketName, err.Error())
 }
 if !exists {
   log.Panicf("bucket %s must exist", bucketName)
 }

}
移除 Buckets
刪除我們創建的 Buckets。

func main() {
ctx := context.Background()

 // bucket name that we created
 bucketName := "test-bucket"

 err := client.RemoveBucket(ctx, bucketName)
 if err != nil {
   log.Panicf("error remeving bucket \"%s\": %s", bucketName, err.Error())
 }

}
刪除對象
func main() {
ctx := context.Background()

 // bucket name that we created
 bucketName := "test-bucket"
 document1Key := "letter1/document.pdf"
 err = client.RemoveObject(ctx, bucketName, document1Key, minio.RemoveObjectOptions{})
 if err != nil {
   fmt.Println("error deleting the bucket object: ", err.Error())
 }

}
您可以使用此完整示例。

筆記

到目前為止,我們僅支持有限的一組 S3 功能,但我們打算在未來幾個月內擴展這些功能。如果您想請求特定功能,請發送電子郵件 [email protected]
您需要將終結點設置為所選庫。buckets.chainsafe.io:443
您需要將 s3 客戶端庫的區域設置為us-east-1
上面示例中的密鑰 ID 是機密。accessKeysecKey

NFT 元數據存儲

不可替代代幣 (NFT) 是獨特的去中心化資產。鏈安全存儲最引人註目的用例之一是存儲與 NFT 相關的鏈下數據。 使用存儲,用戶可以高枕無憂,因為他們知道他們的 NFT 的相關鏈下數據將始終與資產本身一樣可用和去中心化!

先決條件

  • 在 ChainSafe Storage上註冊
  • 創建 API 密鑰
  • 創建 Buckets

在 ChainSafe Storage上註冊

如果您尚未創建帳戶,請轉到 https://app.storage.chainsafe.io

創建 API 密鑰

轉到設置,然後單擊「添加API密鑰」
這將生成密鑰和機密。將您的秘密存儲在安全的地方,就像備份加密錢包的私鑰一樣。它不會再次顯示在設置頁面的 API 密鑰列表中。Storage API Keys
以下所有步驟,我們將使用此密鑰作為<API_SECRET>

創建 Buckets

要將對象存儲在存儲中,您需要創建一個 Buckets。 Buckets是數據的容器。 創建 Buckets時,請提供以下兩個參數作為請求正文:

名稱 - 存 Buckets的名稱。如果您有多個存儲桶,則必須是唯一的
type - 對於存儲中的 Buckets,此值始終為fps
現在,讓我們使用以下 http 請求創建一個 Buckets:

POST /api/v1/buckets HTTP/1.1
Host: https://api.chainsafe.io
Authorization: Bearer <API_SECRET>
Content-Type: application/json
{
    "name": "Test Bucket",
    "type": "fps",
}

你將收到一個帶有 ID 的 json 響應。我們將在以下步驟中引用此 ID。BUCKET_ID

存儲 NFT 數據

要存儲 NFT 數據,您必須提供以下字段:

BUCKET_ID作為路徑參數
path上傳文件數據的路徑。您可以提供不存在的目錄路徑。在這種情況下,還將根據路徑創建目錄。
file您正在上傳的文件
現在,讓我們在路徑上上傳一個文件 ()example_nft/my_data

POST /api/v1/bucket/<BUCKET_ID>/upload HTTP/1.1
Host: https://api.chainsafe.io
Content-Type: multipart/form-data; boundary=----WebKitFormBoundary7MA4YWxkTrZu0gW
Authorization: Bearer <API_SECRET>

----WebKitFormBoundary7MA4YWxkTrZu0gW
Content-Disposition: form-data; name="file"; filename="example_nft"
Content-Type: application/json

(data)
----WebKitFormBoundary7MA4YWxkTrZu0gW
Content-Disposition: form-data; name="path"

/my_data
----WebKitFormBoundary7MA4YWxkTrZu0gW

檢索 NFT 數據

存儲在鏈安全存儲上的 NFT 數據可以從存儲下載 API 或從任何擁有內容的對等方的任何公共 IPFS 網絡訪問。

通過下載端點檢索
只需在 json 請求正文中提供此路徑

POST /api/v1/bucket/<BUCKET_ID>/download HTTP/1.1
Host: https://api.chainsafe.io

Authorization: Bearer <API_SECRET>
Content-Type: application/json

{
    "path": "/my_data/example_nft"
}

通過IPFS網關檢索
首先,獲取上傳文件的 CID。然後,執行以下請求以獲取 json 格式的文件詳細信息:

POST /api/v1/bucket/<BUCKET_ID>/file HTTP/1.1
Host: https://api.chainsafe.io
Authorization: Bearer <API_SECRET>
Content-Type: application/json

{
    "path": "/my_data/example_nft"
}

響應:

{
  "content": {
    "name": "file1.pdf",
    "cid": "QmfPaBnVAR48UbcjF8crcX7TtJKiV8g3DJkTUsBB6pXb7e",
    "size": 10121,
    ...
  },
  ...
}

復製 CID。使用 CID,可以直接從任何公共 IPFS 網關獲取數據。您也可以使用chainsafe的IPFS網關(https://ipfs.chainsafe.io)

URL 應采用以下格式:

https://{gateway URL}/ipfs/{content ID}/{optional path to resource}

如果我們想通過鏈安全的IPFS網關獲取上傳的文件,URL將被 https://ipfs.chainsafe.io/ipfs/QmfPaBnVAR48UbcjF8crcX7TtJKiV8g3DJkTUsBB6pXb7e

你有它。您現在擁有使用 ChainSafe 存儲上傳、存儲和下載 NFT 鏈下數據所需的一切。

認證

持有者身份驗證
令牌可以通過存儲WebIU中的「設置」菜單頒發,並用作標準持有者令牌:

Authorization: Bearer

  • Authorization: Bearer <access-token>

image

2 Likes