Anropa REST API med auktorisering med delad nyckel

Artikel
09/27/2021
15 minuter för att läsa

Den här artikeln visar hur du anropar Azure Storage REST-API:er, inklusive hur du bildar auktoriseringsrubriken. Den skrivs från en utvecklares perspektiv som inte vet något om REST och ingen idé om hur man gör ett REST-anrop. När du har lärt dig hur du anropar en REST-åtgärd kan du använda den här kunskapen för att använda andra Azure Storage REST-åtgärder.

Förutsättningar

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

Installera Visual Studio 2019 med arbetsbelastningen Azure Development.
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 se 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 containrar i bloblagringen i lagringskontot innan du börjar.

Hämta exempelprogrammet

Exempelprogrammet är ett konsolprogram som skrivits 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 leta upp mappen storage-dotnet-rest-api-with-auth, öppna den och dubbelklicka på StorageRestApiAuth.sln.

Om REST

REST står för representationell tillståndsöverföring. En specifik definition finns på Wikipedia.

REST ä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. Den REST API kan anropas från valfri plattform som stöder HTTP/HTTPS. Du kan skriva ett program som körs på en Mac-, Windows-, Linux-, Android-telefon eller surfplatta, iPhone-, iPod- eller webbplats och använda samma REST API för alla dessa plattformar.

Ett anrop till REST API består av en begäran som görs av 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 samt, 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å den åtgärd som anropades, en nyttolast med data.

Om exempelprogrammet

Exempelprogrammet visar en lista över containrarna i ett lagringskonto. När du förstår hur informationen i REST API korrelerar med din faktiska kod är det lättare att ta reda på andra REST-anrop.

Om du tittar på Blob Tjänst-REST-APIser du alla åtgärder som du kan utföra på bloblagring. Lagringsklientbiblioteken är omslutna runt REST-API:erna– de gör det enkelt för dig att komma åt lagringen utan att använda REST-API:erna direkt. Men som nämnts ovan kan du ibland vilja använda REST API i stället för ett lagringsklientbibliotek.

Visa en lista över containeråtgärd

Granska referensen för åtgärden ListContainers. Den här informationen hjälper dig att förstå var några av fälten kommer från i begäran och svaret.

Request-metod: 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ärans-URI skapas från slutpunkten för bloblagringskontot https://myaccount.blob.core.windows.net och resurssträngen /?comp=list .

URI-parametrar:Det finns ytterligare frågeparametrar som du kan använda när du anropar ListContainers. Några av dessa parametrar är timeout 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 att nästa container ska returneras vid nästa begäran. Om du vill använda den här funktionen anger du NextMarker-värdet som markörparameter i URI:en när du gör nästa begäran. När du använder den här funktionen motsvarar det att bläddra 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: Det här avsnittet innehåller de obligatoriska och valfria begärandehuvudena. Tre av huvudena 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 ska använda). Att inkludera x-ms-client-request-id i rubrikerna är valfritt – du kan ange värdet för det här fältet till vad som helst. Den skrivs till lagringsanalysloggarna när loggning är aktiverat.

Begärandetext: Det finns ingen begärandetext för ListContainers. Begärandetexten används på alla PUT-åtgärder när du laddar upp blobar, samt SetContainerAccessPolicy, vilket gör att du kan skicka 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 http-statuskoden 200 ok. En fullständig lista över HTTP-statuskoder finns i Statuskoddefinitioner. Felkoder som är specifika för Storage REST-API:er finns i Vanliga REST API felkoder

Svarshuvuden: Dessa inkluderar innehållstyp; x-ms-request-id, som är det begärande-ID som du skickade. x-ms-version, som anger vilken version av blobtjänsten som används. och datum, som finns 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

Om du vill ha säkerhet när du kör i produktion ska du alltid använda HTTPS i stället för HTTP. I den här övningen bör du använda HTTP så att du kan visa data om begäranden och svar. 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 är lagringskontots namn och nyckel hårdkodade 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 en Azure Key Vault.

I vårt exempelprojekt finns koden för att skapa auktoriseringsrubriken 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". Rubrikkoden Authorization fungerar för de flesta REST API 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 använder något.
Lägg till begärandehuvudena för x-ms-date och x-ms-version.
Hämta auktoriseringsrubriken och lägg till den.

Viss grundläggande information du behöver:

För ListContainers är metoden GET . Det här värdet anges när begäran instansierar.
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å referensdokumentationssidan som visar information om ListContainers-API:et.
URI:en skapas genom att Blob Service-slutpunkten för det lagringskontot skapas och resursen sammanfogas. 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 huvuden.

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 endast bloben om den eTag som du anger matchar den aktuella eTag på bloben. Om någon annan har uppdaterat bloben sedan eTag hämtades åsidosätts inte ändringen.

Ange först uri och payload .

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

Skapa sedan en instans av begäran, ange metoden till GET och ange URI:en.

// 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 huvuden. Ett exempel på ett API som skickar in extra huvuden är ACL-åtgärden Set Container. Det här API-anropet lägger till ett huvud 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 metoden som skapar auktoriseringsrubriken och lägg till den i begärandehuvudena. Du får se hur du skapar auktoriseringsrubriken 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);

Innehåller nu httpRequestMessage REST-begäran med auktoriseringshuvudena.

Skicka begäran

Nu när du har konstruerat begäran kan du anropa SendAsync-metoden för att skicka den till Azure Storage. Kontrollera att värdet för svarsstatuskoden är 200, vilket innebär att åtgärden har lyckats. Parsa sedan svaret. I det här fallet får du en XML-lista över 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 undersöka 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ätverkssiffrare 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örningen:

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 List Containers (Lista containrar) 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 resultatet ska vi se hur du skapar auktoriseringsrubriken. Det är komplicerat att skapa rubriken, men den goda nyheten är att när koden fungerar fungerar den för alla Storage Service REST API:er.

Skapa auktoriseringsrubriken

Tips

Azure Storage stöder nu Azure Active Directory-integrering (Azure AD) för blobar och köer. Azure AD erbjuder en mycket enklare upplevelse för auktorisering av en begäran till Azure Storage. Mer information om hur du använder Azure AD för att auktorisera REST-åtgärder finns i Auktorisera med Azure Active Directory. En översikt över Azure AD-integrering med Azure Storage finns i Autentisera åtkomst till Azure Storage med Azure Active Directory.

Det finns en artikel som förklarar begreppsmässigt (ingen kod) hur du auktoriserar begäranden till Azure Storage.

Nu ska vi gå tillbaka till exakt vad som behövs och visa koden.

Använd först auktorisering med delad nyckel. Formatet för auktoriseringsrubriken 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 HJÄLP av SHA256-algoritmen och sedan kodats med Base64-kodning. Har du det? (Håll dig där, du har inte ens hört ordet kanoniskt ännu.)

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;

De flesta av dessa fält används sällan. För Blob Storage anger du VERB, md5, innehållslängd, kanoniska rubriker och kanonisk resurs. Du kan lämna de andra tomma (men placera i så \n att den vet att de är tomma).

Vad är CanonicalizedHeaders och CanonicalizedResource? Bra fråga! I själva verket, vad betyder kanoniskt? Microsoft Word känner inte ens igen den som ett ord. Det här säger Wikipediaom kanonisering: Inom datavetenskap är kanonik (ibland standardisering eller normalisering) en process för att konvertera data som har mer än en möjlig representation till en "standard", "normal" eller kanonisk form. I normal speak innebär det att du tar listan med objekt (till exempel rubriker när det gäller kanoniska rubriker) och standardiserar dem till ett format som krävs. Microsoft har bestämt sig för ett format och du måste matcha det.

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 huvudena som börjar med "x-ms-" och sorterar dem och formaterar dem sedan till en sträng med [key:value\n] instanser, sammanfogade till 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 den kod som används för att skapa dessa 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();

    // Create the string in the right format; this is what makes the headers "canonicalized" --
    //   it means put in a standard format. https://en.wikipedia.org/wiki/Canonicalization
    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 det lagringskonto som begäran riktas mot. Kom ihåg att URI:n för <http://contosorest.blob.core.windows.net/?comp=list> begäran är , med det faktiska kontonamnet ( i det här contosorest 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 för att fungera 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 auktoriseringsrubriken. Du börjar med att skapa en sträng för 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 det den sista metoden som returnerar auktoriseringsrubriken:

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 som i det här exemplet:

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 det sista huvudet som placeras i begärandehuvudena innan svaret publiceras.

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

Exempel: Lista blobar

Nu ska vi titta på hur du ändrar koden för att anropa åtgärden List Blobs för container container-1. Den här koden är nästan identisk med koden för att lista containrar. De enda skillnaderna är URI:en och hur du parsar svaret.

Om du tittar på referensdokumentationen för ListBlobsser 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 liknar 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: