Anropa REST-API-åtgärder via auktorisering med delad nyckel

Artikel
11/16/2023

Den här artikeln visar hur du anropar en REST API-åtgärd för Azure Storage genom att skapa en auktoriserad REST-begäran med C#. När du har lärt dig hur du anropar en REST API-åtgärd för Blob Storage kan du använda liknande steg för andra Azure Storage REST-åtgärder.

Förutsättningar

Exempelprogrammet visar blobcontainrar för ett lagringskonto. Om du vill testa koden i den här artikeln behöver du följande:

Installera Visual Studio och inkludera arbetsbelastningen För Azure-utveckling . Det här exemplet skapades med Visual Studio 2019. Om du använder en annan version kan vägledningen variera något.
En Azure-prenumeration. Om du inte har någon Azure-prenumeration kan du skapa ett kostnadsfritt konto innan du börjar.
Ett allmänt lagringskonto. Om du ännu inte har ett lagringskonto kan du läsa Skapa ett lagringskonto.
Exemplet i den här artikeln visar hur du listar containrarna i ett lagringskonto. Om du vill se utdata lägger du till några blobcontainrar i lagringskontot innan du börjar.

Hämta exempelprogrammet

Exempelprogrammet är ett konsolprogram skrivet i C#.

Använd git för att ladda ned en kopia av programmet till utvecklingsmiljön.

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

Det här kommandot klonar lagret till den lokala git-mappen. Öppna Visual Studio-lösningen genom att gå till mappen storage-dotnet-rest-api-with-auth och öppna StorageRestApiAuth.sln.

Om REST

REST (Representational State Transfer) är en arkitektur som gör att du kan interagera med en tjänst via ett Internetprotokoll, till exempel HTTP/HTTPS. REST är oberoende av programvaran som körs på servern eller klienten. REST-API:et kan anropas från valfri plattform som stöder HTTP/HTTPS. Du kan skriva ett program som körs på en Mac, Windows, Linux, en Android-telefon eller surfplatta, i Telefon, iPod eller webbplats och använda samma REST-API för alla dessa plattformar.

Ett anrop till REST-API:et består av en begäran från klienten och ett svar som returneras av tjänsten. I begäran skickar du en URL med information om vilken åtgärd du vill anropa, resursen att agera på, eventuella frågeparametrar och huvuden, och beroende på vilken åtgärd som anropades, en nyttolast med data. Svaret från tjänsten innehåller en statuskod, en uppsättning svarshuvuden och, beroende på vilken åtgärd som anropades, en nyttolast med data.

Om exempelprogrammet

Exempelprogrammet visar containrarna i ett lagringskonto. När du förstår hur informationen i REST API-dokumentationen korrelerar med din faktiska kod är andra REST-anrop enklare att ta reda på.

Om du tittar på REST-API:et för Blob Service ser du alla åtgärder som du kan utföra på bloblagring. Lagringsklientbiblioteken omsluter REST-API:erna, vilket gör det enkelt att komma åt lagringsresurser utan att använda REST-API:erna direkt. Ibland kanske du dock vill använda REST-API:et i stället för ett lagringsklientbibliotek.

Åtgärden Listcontainrar

Den här artikeln fokuserar på åtgärden Listcontainrar . Följande information hjälper dig att förstå några av fälten i begäran och svaret.

Begärandemetod: GET. Det här verbet är den HTTP-metod som du anger som en egenskap för begärandeobjektet. Andra värden för det här verbet är HEAD, PUT och DELETE, beroende på vilket API du anropar.

Begärande-URI: https://myaccount.blob.core.windows.net/?comp=list. Begärande-URI:n skapas från slutpunkten https://myaccount.blob.core.windows.net för bloblagringskontot och resurssträngen /?comp=list.

URI-parametrar: Det finns ytterligare frågeparametrar som du kan använda när du anropar ListContainers. Ett par av dessa parametrar överskrider tidsgränsen för anropet (i sekunder) och prefixet, som används för filtrering.

En annan användbar parameter är maxresults: om fler containrar är tillgängliga än det här värdet innehåller svarstexten ett NextMarker-element som anger nästa container som ska returneras vid nästa begäran. Om du vill använda den här funktionen anger du värdet NextMarker som markörparameter i URI:n när du gör nästa begäran. När du använder den här funktionen är det detsamma som att söka igenom resultaten.

Om du vill använda ytterligare parametrar lägger du till dem i resurssträngen med värdet, som i det här exemplet:

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

Begärandehuvuden: I det här avsnittet visas de obligatoriska och valfria begärandehuvudena. Tre av rubrikerna krävs: ett auktoriseringshuvud, x-ms-date (innehåller UTC-tiden för begäran) och x-ms-version (anger vilken version av REST-API:et som ska användas). Det är valfritt att inkludera x-ms-client-request-id i rubrikerna. Du kan ange värdet för det här fältet till vad som helst och det skrivs till lagringsanalysloggarna när loggningen är aktiverad.

Begärandetext: Det finns ingen begärandetext för ListContainers. Begärandetext används för alla PUT-åtgärder vid uppladdning av blobar, inklusive SetContainerAccessPolicy. Med begärandetexten kan du skicka in en XML-lista över lagrade åtkomstprinciper som ska tillämpas. Lagrade åtkomstprinciper beskrivs i artikeln Använda signaturer för delad åtkomst (SAS).

Svarsstatuskod: Anger eventuella statuskoder som du behöver känna till. I det här exemplet är en HTTP-statuskod på 200 ok. En fullständig lista över HTTP-statuskoder finns i Definitioner för statuskod. Information om felkoder som är specifika för REST API:er för lagring finns i Vanliga REST API-felkoder

Svarshuvuden: Dessa inkluderar innehållstyp; x-ms-request-id, vilket är det begärande-ID som du skickade in. x-ms-version, som anger vilken version av blobtjänsten som används, och datum, som är i UTC och anger vilken tid begäran gjordes.

Svarstext: Det här fältet är en XML-struktur som tillhandahåller begärda data. I det här exemplet är svaret en lista över containrar och deras egenskaper.

Skapa REST-begäran

För säkerhet när du kör i produktion använder du alltid HTTPS i stället för HTTP. I den här övningen använder vi HTTP så att du kan visa begärande- och svarsdata. Om du vill visa information om begäran och svar i de faktiska REST-anropen kan du ladda ned Fiddler eller ett liknande program. I Visual Studio-lösningen hårdkodas lagringskontots namn och nyckel i klassen. Metoden ListContainersAsyncREST skickar lagringskontots namn och lagringskontonyckel till de metoder som används för att skapa de olika komponenterna i REST-begäran. I ett verkligt program skulle lagringskontots namn och nyckel finnas i en konfigurationsfil, miljövariabler eller hämtas från ett Azure Key Vault.

I vårt exempelprojekt finns koden för att skapa auktoriseringshuvudet i en separat klass. Tanken är att du kan ta hela klassen och lägga till den i din egen lösning och använda den "som den är". Auktoriseringshuvudkoden fungerar för de flesta REST API-anrop till Azure Storage.

Om du vill skapa begäran, som är ett HttpRequestMessage-objekt, går du till ListContainersAsyncREST i Program.cs. Stegen för att skapa begäran är:

Skapa den URI som ska användas för att anropa tjänsten.
Skapa objektet HttpRequestMessage och ange nyttolasten. Nyttolasten är null för ListContainersAsyncREST eftersom vi inte skickar in något.
Lägg till begärandehuvudena för x-ms-date och x-ms-version.
Hämta auktoriseringshuvudet och lägg till det.

Viss grundläggande information som du behöver:

För ListContainers är GETmetoden . Det här värdet anges när begäran instansieras.
Resursen är frågedelen av URI:n som anger vilket API som anropas, så värdet är /?comp=list. Som tidigare nämnts finns resursen på referensdokumentationsidan som visar information om ListContainers API.
URI:n skapas genom att skapa blobtjänstslutpunkten för det lagringskontot och sammanfoga resursen. Värdet för begärande-URI blir http://contosorest.blob.core.windows.net/?comp=list.
För ListContainers är requestBody null och det finns inga extra rubriker.

Olika API:er kan ha andra parametrar att skicka in, till exempel ifMatch. Ett exempel på var du kan använda ifMatch är när du anropar PutBlob. I så fall anger du ifMatch till en eTag och uppdaterar bara bloben om den eTag du anger matchar den aktuella eTag på bloben. Om någon annan har uppdaterat bloben sedan eTag hämtades åsidosätts inte deras ändring.

uri Ange först och 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;

Instansiera sedan begäran, ange metoden till GET och ange URI:n.

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

Lägg till begärandehuvudena för x-ms-date och x-ms-version. Den här platsen i koden är också där du lägger till eventuella ytterligare begärandehuvuden som krävs för anropet. I det här exemplet finns det inga ytterligare rubriker. Ett exempel på ett API som skickar in extra huvuden är åtgärden Ange container-ACL. Det här API-anropet lägger till en rubrik med namnet "x-ms-blob-public-access" och värdet för åtkomstnivån.

// 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.

Anropa den metod som skapar auktoriseringshuvudet och lägg till den i begärandehuvudena. Auktoriseringshuvudet skapas senare i artikeln. Metodnamnet är GetAuthorizationHeader, som du kan se i det här kodfragmentet:

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

httpRequestMessage Nu innehåller REST-begäran komplett med auktoriseringshuvudena.

Skicka begäran

Nu när du har skapat begäran kan du anropa metoden SendAsync för att skicka den till Azure Storage. Kontrollera att värdet för svarsstatuskoden är 200, vilket innebär att åtgärden har slutförts. Parsa sedan svaret. I det här fallet får du en XML-lista med containrar. Nu ska vi titta på koden för att anropa metoden GetRESTRequest för att skapa begäran, köra begäran och sedan granska svaret för listan över containrar.

    // 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);
            }
        }
    }
}

Om du kör en nätverkssniffare som Fiddler när du anropar SendAsync kan du se information om begäran och svar. Vi tar oss en titt. Namnet på lagringskontot är contosorest.

Begäran:

GET /?comp=list HTTP/1.1

Begärandehuvuden:

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

Statuskod och svarshuvuden som returneras efter körning:

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

Svarstext (XML): För åtgärden Listcontainrar visas listan över containrar och deras egenskaper.

<?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>

Nu när du förstår hur du skapar begäran, anropar tjänsten och parsar resultaten ska vi se hur du skapar auktoriseringshuvudet.

Skapa auktoriseringshuvudet

Dricks

Azure Storage stöder Microsoft Entra-integrering för blobar och köer. Microsoft Entra ID erbjuder en mycket enklare upplevelse för att auktorisera en begäran till Azure Storage. Mer information om hur du använder Microsoft Entra-ID för att auktorisera REST-åtgärder finns i Auktorisera med Microsoft Entra-ID. En översikt över Microsoft Entra-integrering med Azure Storage finns i Autentisera åtkomst till Azure Storage med hjälp av Microsoft Entra-ID.

Mer information om auktoriseringsbegrepp finns i Auktorisera begäranden till Azure Storage.

Nu ska vi destillera artikeln till exakt vad som behövs och visa koden.

Börja med att använda auktorisering av delad nyckel. Formatet för auktoriseringshuvuden ser ut så här:

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

Signaturfältet är en Hash-baserad kod för meddelandeautentisering (HMAC) som skapats från begäran och beräknats med sha256-algoritmen och sedan kodats med Hjälp av Base64-kodning.

Det här kodfragmentet visar formatet för signatursträngen för delad nyckel:

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;

För Blob Storage anger du VERB, md5, innehållslängd, kanoniska rubriker och kanonisk resurs. Du kan lämna de andra tomma i det här exemplet, men ange \n att de är tomma.

Canonicalization är en process för att standardisera data som har mer än en möjlig representation. I det här fallet standardiserar du rubrikerna och resursen. De kanoniska rubrikerna är rubrikerna som börjar med "x-ms-". Den kanoniska resursen är resursens URI, inklusive lagringskontots namn och alla frågeparametrar (till exempel ?comp=list). Den kanoniska resursen innehåller även eventuella ytterligare frågeparametrar som timeout=60du kan ha lagt till, till exempel , .

Vi börjar med de två kanoniska fälten eftersom de krävs för att skapa auktoriseringsrubriken.

Kanoniska rubriker

Om du vill skapa det här värdet hämtar du rubrikerna som börjar med "x-ms-" och sorterar dem och formaterar dem sedan i en sträng med [key:value\n] instanser, sammanfogade i en sträng. I det här exemplet ser de kanoniska rubrikerna ut så här:

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

Här är koden som används för att skapa utdata:

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();
}

Kanonisk resurs

Den här delen av signatursträngen representerar lagringskontot som begäran avser. Kom ihåg att URI för begäran är http://contosorest.blob.core.windows.net/?comp=list, med det faktiska kontonamnet (contosorest i det här fallet). I det här exemplet returneras följande:

/contosorest/\ncomp:list

Om du har frågeparametrar innehåller det här exemplet även dessa parametrar. Här är koden som även hanterar ytterligare frågeparametrar och frågeparametrar med flera värden. Kom ihåg att du skapar den här koden så att den fungerar för alla REST-API:er. Du vill inkludera alla möjligheter, även om metoden ListContainers inte behöver alla.

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();
}

Nu när de kanoniska strängarna har angetts ska vi titta på hur du skapar själva auktoriseringshuvudet. Du börjar med att skapa en sträng med meddelandesignaturen i formatet StringToSign som tidigare visades i den här artikeln. Det här konceptet är enklare att förklara med hjälp av kommentarer i koden, så här är den sista metoden som returnerar auktoriseringshuvudet:

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;
}

När du kör den här koden ser den resulterande MessageSignature ut så här:

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

Här är det slutliga värdet för AuthorizationHeader:

SharedKey contosorest:Ms5sfwkA8nqTRw7Uury4MPHqM6Rj2nfgbYNvUKOa67w=

AuthorizationHeader är den sista rubriken som placeras i begärandehuvudena innan svaret publiceras.

Det omfattar allt du behöver veta för att sätta ihop en klass med vilken du kan skapa en begäran om att anropa REST-API:erna för Storage Services.

Exempel: Lista blobar

Nu ska vi titta på hur du ändrar koden för att anropa listblobbåtgärden för containercontainer-1. Den här koden är nästan identisk med koden för att visa containrar, den enda skillnaden är URI:n och hur du parsar svaret.

Om du tittar på referensdokumentationen för ListBlobs upptäcker du att metoden är GET och RequestURI är:

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

I ListContainersAsyncREST ändrar du koden som anger URI:n till API:et för ListBlobs. Containernamnet är container-1.

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

När du sedan hanterar svaret ändrar du koden så att den söker efter blobar i stället för containrar.

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

När du kör det här exemplet får du resultat som följande:

Kanoniska rubriker:

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

Kanonisk resurs:

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

Meddelandesignatur:

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

Auktoriseringshuvud:

SharedKey contosorest:uzvWZN1WUIv2LYC6e3En10/7EIQJ5X9KtFQqrZkxi6s=

Följande värden kommer från Fiddler: