附註:

針對 C++ 使用 OCI Object Storage Amazon S3 相容 API 與 AWS SDK

簡介

Oracle Cloud Infrastructure (OCI) Object Storage 可讓客戶以其原生格式安全地儲存任何類型的資料。透過內建備援,OCI Object Storage 適合用於建置需要擴展和彈性的現代化應用程式,因為它可用來合併多個資料來源以供分析、備份或封存之用。

OCI Object Storage 是雲端工作負載的基礎,具有彈性、可擴展性、可靠性和成本效益,使它成為雲端非結構化資料的主要儲存體。由於其知名度,因此 OCI Object Storage 使用了龐大的工具生態系統。

OCI Object Storage 提供 Amazon S3 相容 API,客戶可以繼續使用現有的 Amazon S3 工具,並對其應用程式進行最少的變更,以便與 OCI Object Storage 搭配運作。Amazon S3 相容 API 和 OCI Object Storage 資料集都是一致的。如果資料是由 Amazon S3 相容 API 寫入 OCI Object Storage,則可以使用原生 OCI Object Storage API 讀回資料,反之亦然。使用 AWS SDK for C++ 的客戶在使用 Amazon S3 相容性 API 時,可能會發現驗證方面的困難,本教學課程提供兩個簡單的範例來開始使用 C++ 的 AWS SDK。

注意:這些是使用 AWS SDK for C++ 的範例命令檔,不是正式的 Oracle 應用程式,也不是 Oracle 的維護或支援。由於它們是範例,您可以在自己的軟體儲存區域中複查、更新及自訂使用案例。Oracle 不保證或支援第三方 SDK。

目標

必要條件

工作 1:瞭解路徑和虛擬代管樣式 URL

撰寫本教學課程時,OCI Object Storage Amazon S3 相容 API 支援路徑式 URL。這表示儲存桶將位於 URL 路徑中。

舉例而言:

https://MyNamespace.compat.objectstorage.us-ashburn-1.oraclecloud.com/MyBucketName

或者

https://MyNamespace.compat.objectstorage.us-ashburn-1.oraclecloud.com/MyBucketName/MyObjectName

在虛擬代管樣式 URL 中,OCI 物件儲存的儲存桶名稱會包含在 URL 的子網域 (或開頭) 中。

舉例而言:

https://MyBucketName.MyNamespace.compat.objectstorage.us-ashburn-1.oraclecloud.com

或者

https://MyBucketName.MyNamespace.compat.objectstorage.us-ashburn-1.oraclecloud.com/MyObjectName

依照預設,C++ 的 AWS SDK 會使用虛擬代管樣式 URL。遵循 AWS 所產生的程式碼範例,以及從 OCI 租用戶替換值時,會顯示類似以下輸出的錯誤。如需詳細資訊,請參閱建立、列出及刪除儲存桶

curlCode: 60, SSL peer certificate or SSH remote key was not OK 

由於程式碼使用虛擬代管樣式 URL,因此程式碼不會參照 OCI 物件儲存的儲存桶或有效的憑證。

必須變更 S3Client 設定,才能使用路徑樣式 URL。配置應使用下列指令進行設定。

Aws::Client::ClientConfiguration config; 

S3Client s3Client(config, Aws::Client::AWSAuthV4Signer::PayloadSigningPolicy::Never, false); 

作業 2:決定您的租用戶命名空間和 S3 API 區間

  1. 登入您的 Linux 系統。

    注意:所有命令都將從您已安裝並設定必要先決條件的 Linux 系統執行。

  2. 執行 oci os ns get-metadata OCI CLI 命令。

    $ oci os ns get-metadata
    {
      "data": {
        "default-s3-compartment-id": "ocid1.tenancy.oc1..bbbbcccdabcc0x0aaaaaa00aaaaaaaaaaa0b0b00ccccccccbbbbbbbb00aa",
        "default-swift-compartment-id": "ocid1.tenancy.oc1..bbbbcccdabcc0x0aaaaaa00aaaaaaaaaaa0b0b00ccccccccbbbbbbbb00aa",
        "namespace": "MyNamespace"
      }
    }
    
  3. S3 區間 OCID 若包含 tenancy 這個字,即為根區間。使用下列指令取得名稱。

    $ oci iam compartment get --compartment-id <compartment_ocid>
    

    或者,對於租用戶根區間,請執行下列命令。

    $ oci iam tenancy get --tenancy-id <tenancy_ocid>
    

    或者,您可以瀏覽至右上角的設定檔,然後選取租用戶 (your_tenancy_name) 來決定命名空間和 S3 API 區間,以使用 OCI 主控台。

    OCI 租用戶畫面

    S3 區間將會在任務 4 中再次使用。

作業 3:建立客戶秘密金鑰以存取 S3 相容 API

使用 OCI CLI 命令產生秘密金鑰。

  1. 執行 oci iam customer-secret-key create 指令。

    oci iam customer-secret-key create --display-name display-name --user-id ocid1.user.oc1..aaaaaaaa-user-ocid-sdd6ahdouq
    {
    "data": {
         "display-name": "display-name",
         "id": "7aaaa3462aa34271a276002015f30674a5325aaa",
         "inactive-status": null,
         "key": "1aaa577aaaa/aa3aa92aa7aa7aaaaaaAa0aaaAa8AAa=",
         "lifecycle-state": "ACTIVE",
         "time-created": "2024-07-19T19:58:03.794000+00:00",
         "time-expires": null,
         "user-id": "ocid1.user.oc1..aaaaaaaa-user-ocid-sdd6ahdouq"
    },
    "etag": "e63038c73fc24fa087a2a4c3339ef709"
    }
    
  2. 將 ID (AWS_ACCESS_KEY_ID) 和索引鍵 (AWS_SECRET_ACCESS_KEY) 複製到安全位置,以供日後用來設定環境變數。

    注意:您可以在 OCI CLI 組態檔中找到您的使用者 OCID,通常儲存在 $HOME/.oci/config 中。

也可以使用 OCI 主控台產生秘密金鑰,然後瀏覽至右上角的設定檔,然後選取顯示的使用者名稱。按一下客戶秘密金鑰連結、產生秘密金鑰,然後設定顯示名稱。按一下複製並將秘密金鑰儲存在安全位置,然後按一下關閉

從設定檔瀏覽至「客戶秘密金鑰」

關閉產生秘密金鑰視窗後,請尋找客戶秘密金鑰清單中的顯示名稱,將滑鼠游標停留在存取金鑰上,然後複製存取金鑰。

複製存取金鑰

作業 4:收集設定的時段資訊

  1. 移至 OCI 主控台,瀏覽至儲存並按一下儲存桶

  2. 按一下先決條件中的儲存桶名稱,並記下下列資訊。

    • 儲存桶名稱
    • 物件的位置,這將會是前置碼。
    • 區域名稱。請從此處取得區域碼:區域與可用性網域。例如,US East (Ashburn) 會以 us-ashburn-1 表示。

    收集用於設定的儲存桶和物件資訊

作業 5:設定環境變數

使用下列命令,根據先前作業的資訊設定環境變數。

export AWS_ACCESS_KEY_ID="<your access key ID from Task 3>"
export AWS_SECRET_ACCESS_KEY="<your secret key ID from Task 3>"
export OCI_REGION="bukcet region from Task 4>"
export OCI_NAMESPACE="<namespace name from Task 1>"
export OCI_BUCKET="<your bucket name from Task 4>"
export OCI_PREFIX="<object prefix name from Task 4>"

舉例而言:

export AWS_ACCESS_KEY_ID="da34baaa4ab029f51c34c1cee83d40f0dEXAMPLE" 
export AWS_SECRET_ACCESS_KEY="7w3uMS6kYiYkUpziSlLFcBimBsYDJfojwCWKEXAMPLE=" 
export OCI_REGION="us-ashburn-1" 
export OCI_NAMESPACE="MyNamespace"
export OCI_BUCKET="Images" 
export OCI_PREFIX="2024/12/18/Camera" 

工作 6:建立 C++ 範例

  1. 執行下列命令以複製 git 中的範例儲存區域。

    $ git clone https://github.com/tonymarkel/OCI_AWS_CPP_SDK_S3_Examples.git
    
  2. 執行下列指令,以變更至包含 C++ 範例的目錄、建立目錄、變更至該目錄,然後執行編譯並建立。

    $ OCI_AWS_CPP_SDK_S3_Examples 
    $ mkdir build 
    $ cd build 
    $ cmake .. 
    $ make 
    

注意:這些是使用 AWS SDK for C++ 的範例命令檔,不是正式的 Oracle 應用程式,也不是 Oracle 的維護或支援。由於它們是範例,您可以在自己的軟體儲存區域中複查、更新及自訂使用案例。Oracle 不保證或支援第三方 SDK。

作業 7:執行範例

  1. 執行下列命令以取得儲存桶清單。

    $ ./listBuckets $OCI_NAMESPACE $OCI_REGION $AWS_ACCESS_KEY_ID $AWS_SECRET_ACCESS_KEY 
    

    舉例而言:

    $ ./listBuckets $OCI_NAMESPACE $OCI_REGION $AWS_ACCESS_KEY_ID $AWS_SECRET_ACCESS_KEY 
    S3 Endpoint is: https://MyNamespace.compat.objectstorage.us-ashburn-1.oraclecloud.com/ 
    Found 3 buckets 
    Demo 
    Images 
    Logs 
    
  2. 執行下列命令以取得物件清單。

    舉例而言:

    $ ./listObjects $OCI_NAMESPACE $OCI_REGION $AWS_ACCESS_KEY_ID $AWS_SECRET_ACCESS_KEY $OCI_BUCKET $OCI_PREFIX 
    S3 Object Path is: https://MyNamespace.compat.objectstorage.us-ashburn-1.oraclecloud.com 
    Bucket is: Images 
    Prefix is: 2024/12/18/Camera 
    LISTING OBJECTS 
    Found 3 objects 
    2024/12/18/Camera/Image1.jpeg 
    2024/12/18/Camera/Image2.jpeg 
    2024/12/18/Camera/DefinitelyNotACat.jpeg 
    

注意:如果發生問題,請回到「工作 5」,並確定您的環境變數設定正確。

認可

其他學習資源

探索 docs.oracle.com/learn 上的其他實驗室,或存取 Oracle Learning YouTube 頻道上的更多免費學習內容。此外,請造訪 education.oracle.com/learning-explorer 以成為 Oracle Learning Explorer。

如需產品文件,請造訪 Oracle Help Center