使用共用金鑰授權呼叫 REST API 作業

發行項
03/20/2024

本文說明如何使用 C# 建立授權的 REST 要求以呼叫 Azure 儲存體 REST API 作業。了解如何呼叫 Blob 儲存體的 REST API 作業之後，您可以針對任何其他 Azure 儲存體 REST 作業使用類似的步驟。

必要條件

範例應用程式會列出儲存體帳戶的 Blob 容器。若要試用本文中的程式碼，您需要下列項目︰

安裝 Visual Studio 並納入 Azure 開發工作負載。這個範例是使用 Visual Studio 2019 建置的。如果您使用不同的版本，則指導可能會稍有不同。
Azure 訂用帳戶。如果您沒有 Azure 訂用帳戶，請在開始前建立免費帳戶。
一般用途的儲存體帳戶。如果您還沒有儲存體帳戶，請參閱建立儲存體帳戶。
本文中的範例示範如何列出儲存體帳戶中的容器。若要查看輸出，請在開始之前，將一些 Blob 容器新增至儲存體帳戶。

下載範例應用程式

範例應用程式是以 C# 撰寫的主控台應用程式。

使用 git 將應用程式的複本下載至您的開發環境。

git clone https://github.com/Azure-Samples/storage-dotnet-rest-api-with-auth.git

此命令會將存放庫複製到本機的 git 資料夾。若要開啟 Visual Studio 解決方案，請瀏覽至 storage-dotnet-rest-api-with-auth 資料夾，然後開啟 StorageRestApiAuth.sln。

關於 REST

具象狀態傳輸 (REST) 是一種架構，可讓您透過網際網路通訊協定 (例如 HTTP/HTTPS) 與服務互動。 REST 與執行於伺服器或用戶端上的軟體相互獨立。 REST API 可從任何支援 HTTP/HTTPS 的平台呼叫。您可以撰寫在 Mac、Windows、Linux、Android 手機或平板電腦、iPhone、iPod 或網站上執行的應用程式，並針對上述這些平台使用相同的 REST API。

對 REST API 的呼叫由用戶端所提出的要求和服務傳回的回應所組成。在要求中，您會傳送一個 URL，其中包含關於您想要呼叫的作業、要處理的資源、任何查詢參數和標頭，以及資料的承載 (視呼叫的作業而定) 的資訊。服務的回應中包含狀態碼、一組回應標頭，以及資料的承載 (視呼叫的作業而定)。

關於範例應用程式

範例應用程式會列出儲存體帳戶中的容器。了解 REST API 文件中的資訊如何與實際的程式碼相互關聯後，就比較容易找出其他 REST 呼叫。

如果您查看 Blob 服務 REST API，您會看到可以在 blob 儲存體上執行的所有作業。儲存體用戶端程式庫以 REST API 為主的包裝函式，可讓您輕鬆地存取儲存體資源，而無需直接使用 REST API。不過，有時候，您可能會想要使用 REST API，而不是儲存體用戶端程式庫。

列出容器作業

本文著重於列出容器作業。下列資訊可協助您了解要求和回應中的一些欄位。

要求方法：GET。此動詞命令是您指定作為要求物件屬性的 HTTP 方法。視您呼叫的 API 而定，此動詞命令的其他值包括 HEAD、PUT 和 DELETE。

要求 URI：https://myaccount.blob.core.windows.net/?comp=list。要求 URI 是從 Blob 儲存體帳戶端點 https://myaccount.blob.core.windows.net 和資源字串 /?comp=list 建立的。

URI 參數：呼叫 ListContainers 時，您有其他查詢參數可以使用。其中有幾個參數是呼叫的 timeout (以秒為單位) 以及用於篩選的 prefix。

另一個有用參數是 maxresults：，而如果可用的容器超出這個值，回應主體會包含 NextMarker 元素，以指出要在下一個要求中傳回的下一個容器。若要使用此功能，您可在提出下一個要求時，於 URI 中提供 NextMarker 值作為 marker 參數。使用此功能時，類似於逐頁瀏覽結果。

若要使用其他參數，請將它們附加至資源字串，其值如下列範例所示：

/?comp=list&timeout=60&maxresults=100

要求標頭：此區段列出必要及選用的要求標頭。三個必要標頭：Authorization 標頭、x-ms-date (包含要求的 UTC 時間) 及 x-ms-version (指定要使用的 REST API 版本)。在標頭中包含 x-ms-client-request-id 是選擇性的。您可以將此欄位的值設定為任意值，並在啟用記錄時寫入儲存體分析記錄。

要求主體：ListContainers 沒有要求主體。上傳 Blob 時，要求本文會用於所有 PUT 作業，包括 SetContainerAccessPolicy。要求本文可讓您傳送 XML 清單，列出要套用的存取原則。使用共用存取簽章 (SAS) 一文會討論預存存取原則。

回應狀態碼：告知您需要知道的任何狀態碼。在此範例中，HTTP 狀態碼 200 表示「正常」。如需完整的 HTTP 狀態碼清單，請參閱狀態碼定義。若要查看儲存體 REST API 特有的錯誤碼，請參閱常見的 REST API 錯誤碼

回應標頭：包括「內容類型」、x-ms-request-id (您傳入的要求識別碼)、x-ms-version (表示使用的 Blob 服務版本) 和「日期」 (UTC，指出提出要求的時間)。

回應主體：這個欄位是一種 XML 結構，可提供所要求的資料。在此範例中，回應是容器及其屬性的清單。

建立 REST 要求

為確保在生產環境執行時的安全性，請一律使用 HTTPS，而非 HTTP。基於此練習的目的，我們會使用 HTTP，以便您檢視要求和回應資料。若要檢視實際 REST 呼叫中的要求和回應資訊，您可以下載 Fiddler 或類似的應用程式。在 Visual Studio 解決方案中，儲存體帳戶名稱和金鑰會在類別中硬式編碼。 ListContainersAsyncREST 方法會將儲存體帳戶名稱和儲存體帳戶金鑰傳至用來建立各種 REST 要求元件的方法。在真實世界的應用程式中，儲存體帳戶名稱和金鑰會位於組態檔、環境變數，或從 Azure Key Vault 擷取而來。

在我們的範例專案中，用來建立授權標頭的程式碼位於個別的類別中。其概念是，您可以採用整個類別，並將其新增至您自己的解決方案，並以「現狀」加以使用。授權標頭程式碼適用於對 Azure 儲存體的大部分 REST API 呼叫。

若要建立要求 (也就是 HttpRequestMessage 物件)，請移至 Program.cs 中的 ListContainersAsyncREST。建立要求的步驟如下：

建立要用於呼叫服務的 URI。
建立 HttpRequestMessage 物件並設定承載。 ListContainersAsyncREST 的承載為 null，因為我們並未傳入任何項目。
新增 x-ms-date 和 x-ms-version 的要求標頭。
取得授權標頭並加以新增。

您需要的一些基本資訊：

對 ListContainers 而言，方法是 GET。此值會在具現化要求時設定。
資源是 URI 的查詢部份，其可指出正在呼叫哪一個 API，所以此值為 /?comp=list。如前文所述，資源位於參考文件頁面上，可顯示 ListContainers API 的相關資訊。
建立該儲存體帳戶的 Blob 服務端點並串連資源，即可建構 URI。 要求 URI 的值最終是 http://contosorest.blob.core.windows.net/?comp=list。
對 ListContainers 而言，requestBody 為 null，而且沒有額外的標頭。

不同的 API 可能有其他要傳入的參數，例如 ifMatch。舉例來說，在呼叫 PutBlob 時，即可能會使用 ifMatch。在此情況下，您將 ifMatch 設定為 eTag，而它只會在您提供的 eTag 符合 blob 上目前的 eTag 時更新 blob。如果有其他人在擷取 eTag 後更新 blob，將不會覆寫其變更。

首先，設定 uri 和 requestPayload。

// Construct the URI. It will look like this:
//   https://myaccount.blob.core.windows.net/resource
String uri = string.Format("http://{0}.blob.core.windows.net?comp=list", storageAccountName);

// Provide the appropriate payload, in this case null.
//   we're not passing anything in.
Byte[] requestPayload = null;

接著，將要求具現化，將方法設定為 GET 並提供 URI。

// Instantiate the request message with a null payload.
using (var httpRequestMessage = new HttpRequestMessage(HttpMethod.Get, uri)
{ Content = (requestPayload == null) ? null : new ByteArrayContent(requestPayload) })
{

新增 x-ms-date 和 x-ms-version 的要求標頭。程式碼中的這個位置也就是您新增呼叫所需之任何其他要求標頭的位置。在此範例中，沒有任何額外的標頭。例如，「設定容器 ACL」作業即為傳入額外標頭的 API。此 API 呼叫會新增名為 "x-ms-blob-public-access" 的標頭以及存取層級的值。

// Add the request headers for x-ms-date and x-ms-version.
DateTime now = DateTime.UtcNow;
httpRequestMessage.Headers.Add("x-ms-date", now.ToString("R", CultureInfo.InvariantCulture));
httpRequestMessage.Headers.Add("x-ms-version", "2017-07-29");
// If you need any additional headers, add them here before creating
//   the authorization header.

呼叫可建立授權標頭的方法，並將它新增至要求標頭。授權標頭會在本文稍後部分建立。此方法名稱是 GetAuthorizationHeader，您可以在此程式碼片段中看到該方法：

// Get the authorization header and add it.
httpRequestMessage.Headers.Authorization = AzureStorageAuthenticationHelper.GetAuthorizationHeader(
    storageAccountName, storageAccountKey, now, httpRequestMessage);

此時，httpRequestMessage 包含帶有授權標頭的 REST 要求。

傳送要求

現在您已建構要求，接下來可以呼叫 SendAsync 方法，將其傳送至 Azure 儲存體。確認回應狀態碼的值為 200，這表示作業已成功。接著，剖析回應。在此情況下，您會取得容器的 XML 清單。讓我們查看用於呼叫 GetRESTRequest 方法以建立要求的程式碼，執行此要求，然後檢查容器清單的回應。

    // Send the request.
    using (HttpResponseMessage httpResponseMessage =
      await new HttpClient().SendAsync(httpRequestMessage, cancellationToken))
    {
        // If successful (status code = 200),
        //   parse the XML response for the container names.
        if (httpResponseMessage.StatusCode == HttpStatusCode.OK)
        {
            String xmlString = await httpResponseMessage.Content.ReadAsStringAsync();
            XElement x = XElement.Parse(xmlString);
            foreach (XElement container in x.Element("Containers").Elements("Container"))
            {
                Console.WriteLine("Container name = {0}", container.Element("Name").Value);
            }
        }
    }
}

如果您在呼叫 SendAsync 時執行網路 sniffer (例如 Fiddler)，您可以看到要求和回應資訊。讓我看看。儲存體帳戶的名稱為 contosorest。

要求：

GET /?comp=list HTTP/1.1

要求標頭：

x-ms-date: Thu, 16 Nov 2017 23:34:04 GMT
x-ms-version: 2014-02-14
Authorization: SharedKey contosorest:1dVlYJWWJAOSHTCPGiwdX1rOS8B4fenYP/VrU0LfzQk=
Host: contosorest.blob.core.windows.net
Connection: Keep-Alive

執行後傳回的狀態碼和回應標頭：

HTTP/1.1 200 OK
Content-Type: application/xml
Server: Windows-Azure-Blob/1.0 Microsoft-HTTPAPI/2.0
x-ms-request-id: 3e889876-001e-0039-6a3a-5f4396000000
x-ms-version: 2017-07-29
Date: Fri, 17 Nov 2017 00:23:42 GMT
Content-Length: 1511

回應主體 (XML)：對於「列出容器」作業，這會顯示容器及其屬性的清單。

<?xml version="1.0" encoding="utf-8"?>
<EnumerationResults
  ServiceEndpoint="http://contosorest.blob.core.windows.net/">
  <Containers>
    <Container>
      <Name>container-1</Name>
      <Properties>
        <Last-Modified>Thu, 16 Mar 2017 22:39:48 GMT</Last-Modified>
        <Etag>"0x8D46CBD5A7C301D"</Etag>
        <LeaseStatus>unlocked</LeaseStatus>
        <LeaseState>available</LeaseState>
      </Properties>
    </Container>
    <Container>
      <Name>container-2</Name>
      <Properties>
        <Last-Modified>Thu, 16 Mar 2017 22:40:50 GMT</Last-Modified>
        <Etag>"0x8D46CBD7F49E9BD"</Etag>
        <LeaseStatus>unlocked</LeaseStatus>
        <LeaseState>available</LeaseState>
      </Properties>
    </Container>
    <Container>
      <Name>container-3</Name>
      <Properties>
        <Last-Modified>Thu, 16 Mar 2017 22:41:10 GMT</Last-Modified>
        <Etag>"0x8D46CBD8B243D68"</Etag>
        <LeaseStatus>unlocked</LeaseStatus>
        <LeaseState>available</LeaseState>
      </Properties>
    </Container>
    <Container>
      <Name>container-4</Name>
      <Properties>
        <Last-Modified>Thu, 16 Mar 2017 22:41:25 GMT</Last-Modified>
        <Etag>"0x8D46CBD93FED46F"</Etag>
        <LeaseStatus>unlocked</LeaseStatus>
        <LeaseState>available</LeaseState>
        </Properties>
      </Container>
      <Container>
        <Name>container-5</Name>
        <Properties>
          <Last-Modified>Thu, 16 Mar 2017 22:41:39 GMT</Last-Modified>
          <Etag>"0x8D46CBD9C762815"</Etag>
          <LeaseStatus>unlocked</LeaseStatus>
          <LeaseState>available</LeaseState>
        </Properties>
      </Container>
  </Containers>
  <NextMarker />
</EnumerationResults>

既然您了解如何建立要求、呼叫服務，以及剖析結果，讓我們看看如何建立授權標頭。

建立授權標頭

提示

Azure 儲存體支援 Blob 和佇列的 Microsoft Entra 整合。 Microsoft Entra ID 可提供更簡單的 Azure 儲存體要求授權體驗。如需使用 Microsoft Entra ID 來授權 REST 作業的詳細資訊，請參閱使用 Microsoft Entra ID 進行授權 (部分機器翻譯)。如需 Microsoft Entra 與 Azure 儲存體整合的概觀，請參閱使用Microsoft Entra ID 來驗證 Azure 儲存體的存取權 (部分機器翻譯)。

若要深入了解授權概念，請參閱授權對 Azure 儲存體的要求 (部分機器翻譯)。

讓我們萃取該文章的精華，並顯示程式碼。

首先，請使用共用金鑰授權。授權標頭格式如下所示：

Authorization="SharedKey <storage account name>:<signature>"

簽章欄位是雜湊式訊息驗證碼 (HMAC)，該驗證碼是從要求建構而來並使用 SHA256 演算法進行計算，然後使用 Base64 編碼方式進行編碼。

此程式碼片段會顯示共用金鑰簽章字串的格式：

StringToSign = VERB + "\n" +  
               Content-Encoding + "\n" +  
               Content-Language + "\n" +  
               Content-Length + "\n" +  
               Content-MD5 + "\n" +  
               Content-Type + "\n" +  
               Date + "\n" +  
               If-Modified-Since + "\n" +  
               If-Match + "\n" +  
               If-None-Match + "\n" +  
               If-Unmodified-Since + "\n" +  
               Range + "\n" +  
               CanonicalizedHeaders +  
               CanonicalizedResource;

對於 Blob 儲存體，您可以指定 VERB、md5、內容長度、正式標頭和正式資源。在此範例中Ｍ，您可以將其他資訊留空，但請輸入 \n 以指出它們為空。

標準化是對有多種可能表示形式的資料進行標準化的流程。在此情況下，您會將標頭和資源標準化。標準化的標頭是以「x-ms-」開頭的標頭。標準化的資源是資源的 URI，包括儲存體帳戶名稱和所有查詢參數 (例如 ?comp=list)。標準化的資源也包含您可能新增的任何其他查詢參數，例如 timeout=60。

讓我們從這兩個標準化的欄位著手，因為需有它們才能建立授權標頭。

正式標頭

若要建立此值，請擷取以 "x-ms-" 開頭的標頭並加以排序，然後將它們格式化成 [key:value\n] 執行個體的字串 (串連成一個字串)。此範例中，正式標頭如下所示：

x-ms-date:Fri, 17 Nov 2017 00:44:48 GMT\nx-ms-version:2017-07-29\n

以下是用來建立該輸出的程式碼：

private static string GetCanonicalizedHeaders(HttpRequestMessage httpRequestMessage)
{
    var headers = from kvp in httpRequestMessage.Headers
        where kvp.Key.StartsWith("x-ms-", StringComparison.OrdinalIgnoreCase)
        orderby kvp.Key
        select new { Key = kvp.Key.ToLowerInvariant(), kvp.Value };

    StringBuilder headersBuilder = new StringBuilder();

    foreach (var kvp in headers)
    {
        headersBuilder.Append(kvp.Key);
        char separator = ':';

        // Get the value for each header, strip out \r\n if found, then append it with the key.
        foreach (string headerValue in kvp.Value)
        {
            string trimmedValue = headerValue.TrimStart().Replace("\r\n", string.Empty);
            headersBuilder.Append(separator).Append(trimmedValue);

            // Set this to a comma; this will only be used
            // if there are multiple values for one of the headers.
            separator = ',';
        }

        headersBuilder.Append("\n");
    }

    return headersBuilder.ToString();
}

正式資源

這部分的簽章字串代表作為要求目標的儲存體帳戶。請記住，要求 URI 是 http://contosorest.blob.core.windows.net/?comp=list，具有實際帳戶名稱 (在此情況下是 contosorest)。在此範例中，傳回的內容如下：

/contosorest/\ncomp:list

如果您有查詢參數，此範例也會包含這些參數。以下的程式碼也會處理其他查詢參數，以及具有多個值的查詢參數。請記住，您要將此程式碼建置成適用於所有的 REST API。即使 ListContainers 方法不需要所有的可能性，您仍想將其全部納入。

private static string GetCanonicalizedResource(Uri address, string storageAccountName)
{
    // The absolute path will be "/" because for we're getting a list of containers.
    StringBuilder sb = new StringBuilder("/").Append(storageAccountName).Append(address.AbsolutePath);

    // Address.Query is the resource, such as "?comp=list".
    // This ends up with a NameValueCollection with 1 entry having key=comp, value=list.
    // It will have more entries if you have more query parameters.
    NameValueCollection values = HttpUtility.ParseQueryString(address.Query);

    foreach (var item in values.AllKeys.OrderBy(k => k))
    {
        sb.Append('\n').Append(item.ToLower()).Append(':').Append(values[item]);
    }

    return sb.ToString();
}

現在已設定正式字串，讓我們看看如何建立授權標頭本身。首先以本文先前顯示的 StringToSign 格式，建立訊息簽章的字串。這個概念比較容易說明在程式碼中使用註解，所以下面是傳回授權標頭的最後一個方法：

internal static AuthenticationHeaderValue GetAuthorizationHeader(
    string storageAccountName, string storageAccountKey, DateTime now,
    HttpRequestMessage httpRequestMessage, string ifMatch = "", string md5 = "")
{
    // This is the raw representation of the message signature.
    HttpMethod method = httpRequestMessage.Method;
    String MessageSignature = String.Format("{0}\n\n\n{1}\n{5}\n\n\n\n{2}\n\n\n\n{3}{4}",
                method.ToString(),
                (method == HttpMethod.Get || method == HttpMethod.Head) ? String.Empty
                  : httpRequestMessage.Content.Headers.ContentLength.ToString(),
                ifMatch,
                GetCanonicalizedHeaders(httpRequestMessage),
                GetCanonicalizedResource(httpRequestMessage.RequestUri, storageAccountName),
                md5);

    // Now turn it into a byte array.
    byte[] SignatureBytes = Encoding.UTF8.GetBytes(MessageSignature);

    // Create the HMACSHA256 version of the storage key.
    HMACSHA256 SHA256 = new HMACSHA256(Convert.FromBase64String(storageAccountKey));

    // Compute the hash of the SignatureBytes and convert it to a base64 string.
    string signature = Convert.ToBase64String(SHA256.ComputeHash(SignatureBytes));

    // This is the actual header that will be added to the list of request headers.
    AuthenticationHeaderValue authHV = new AuthenticationHeaderValue("SharedKey",
        storageAccountName + ":" + signature);
    return authHV;
}

當您執行此程式碼時，所產生的 MessageSignature 如下列範例所示：

GET\n\n\n\n\n\n\n\n\n\n\n\nx-ms-date:Fri, 17 Nov 2017 01:07:37 GMT\nx-ms-version:2017-07-29\n/contosorest/\ncomp:list

以下是最終的 AuthorizationHeader 值：

SharedKey contosorest:Ms5sfwkA8nqTRw7Uury4MPHqM6Rj2nfgbYNvUKOa67w=

AuthorizationHeader 是在張貼回應之前，放在要求標頭中的最後一個標頭。

其中涵蓋您所需的一切資訊，以建構一個類別，讓您據以建立呼叫儲存體服務 REST API 要求。

範例：列出 Blob

我們來看看如何變更程式碼，以呼叫容器 container-1 的「列出 Blob」作業。這段程式碼與用於列出容器的程式碼幾乎相同，唯一的差異在於 URI 及剖析回應的方式。

如果您查看 ListBlobs 的參考文件，您會發現此方法為 GET 且 RequestURI 為：

https://myaccount.blob.core.windows.net/container-1?restype=container&comp=list

在 ListContainersAsyncREST 中，將設定 URI 的程式碼變更為 ListBlobs 的 API。容器的名稱是 container-1。

String uri =
    string.Format("http://{0}.blob.core.windows.net/container-1?restype=container&comp=list",
      storageAccountName);

然後在您處理回應的地方，變更程式碼以尋找 blob，而不是容器。

foreach (XElement container in x.Element("Blobs").Elements("Blob"))
{
    Console.WriteLine("Blob name = {0}", container.Element("Name").Value);
}

當您執行此範例時，您會取得如下所示的結果：

正式標頭：

x-ms-date:Fri, 17 Nov 2017 05:16:48 GMT\nx-ms-version:2017-07-29\n

正式資源：

/contosorest/container-1\ncomp:list\nrestype:container

訊息簽章：

GET\n\n\n\n\n\n\n\n\n\n\n\nx-ms-date:Fri, 17 Nov 2017 05:16:48 GMT
  \nx-ms-version:2017-07-29\n/contosorest/container-1\ncomp:list\nrestype:container

授權標頭：

SharedKey contosorest:uzvWZN1WUIv2LYC6e3En10/7EIQJ5X9KtFQqrZkxi6s=

下列值來自 Fiddler：