Znajdowanie obiektów blob według tagów

  • Artykuł

Operacja Find Blobs by Tags znajduje wszystkie obiekty blob na koncie magazynu, których tagi pasują do wyrażenia wyszukiwania.

Żądanie

Żądanie można skonstruować Find Blobs by Tags w następujący sposób. Zalecamy użycie protokołu HTTPS. Zastąp ciąg myaccount nazwą konta magazynu.

IDENTYFIKATOR URI żądania GET Wersja PROTOKOŁU HTTP
https://myaccount.blob.core.windows.net?comp=blobs&where=<expression> HTTP/1.1

Parametry identyfikatora URI

W identyfikatorze URI żądania można określić następujące dodatkowe parametry:

Parametr Opis
expression Wymagane. Filtruje zestaw wyników tak, aby zawierał tylko obiekty blob, których tagi pasują do określonego wyrażenia.

Aby uzyskać więcej informacji na temat tworzenia tego wyrażenia, zobacz Uwagi.
marker Opcjonalny. Wartość ciągu, która identyfikuje część zestawu wyników, która ma zostać zwrócona przy użyciu następnej operacji. Operacja zwraca wartość znacznika w treści odpowiedzi, jeśli zwrócony zestaw wyników nie został ukończony. Następnie można użyć wartości znacznika w kolejnym wywołaniu, aby zażądać następnego zestawu elementów.

Wartość znacznika jest nieprzezroczysta dla klienta.
maxresults Opcjonalny. Określa maksymalną liczbę obiektów blob do zwrócenia. Jeśli żądanie nie określa maxresults lub określa wartość większą niż 5000, serwer zwraca maksymalnie 5000 elementów. Jeśli zostaną zwrócone dodatkowe wyniki, usługa zwróci token kontynuacji NextMarker w elemecie odpowiedzi. W niektórych przypadkach usługa może zwrócić mniej wyników niż maxresults określono. Usługa może również zwrócić token kontynuacji.

Ustawienie maxresults wartości mniejszej lub równej zero powoduje wyświetlenie kodu odpowiedzi błędu 400 (nieprawidłowe żądanie).
timeout Opcjonalny. Wyrażone w sekundach. Aby uzyskać więcej informacji, zobacz Ustawianie limitów czasu dla operacji usługi Blob Storage.

Nagłówki żądań

W poniższej tabeli opisano wymagane i opcjonalne nagłówki żądań:

Nagłówek żądania Opis
Authorization Wymagane. Określa schemat autoryzacji, nazwę konta i podpis. Aby uzyskać więcej informacji, zobacz Autoryzowanie żądań do usługi Azure Storage.
Date lub x-ms-date Wymagane. Określa dla żądania godzinę w formacie uniwersalnego czasu koordynowanego (UTC). Aby uzyskać więcej informacji, zobacz Autoryzowanie żądań do usługi Azure Storage.
x-ms-version Wymagane dla wszystkich autoryzowanych żądań, ale opcjonalnych dla żądań anonimowych. Określa wersję operacji do użycia dla tego żądania. Aby uzyskać więcej informacji, zobacz Przechowywanie wersji usług Azure Storage.
x-ms-client-request-id Opcjonalny. Udostępnia nieprzezroczystą wartość wygenerowaną przez klienta z limitem znaków 1-kibibyte (KiB), który jest rejestrowany w dziennikach podczas konfigurowania rejestrowania. Zdecydowanie zalecamy używanie tego nagłówka do korelowania działań po stronie klienta z żądaniami odbieranymi przez serwer.

Treść żądania

Brak.

Reakcja

Odpowiedź zawiera kod stanu HTTP, nagłówki odpowiedzi i treść odpowiedzi.

Kod stanu

Operacja zakończona powodzeniem zwraca kod stanu 200 (OK).

Aby uzyskać informacje o kodach stanu, zobacz Stan i kody błędów.

Nagłówki odpowiedzi

Odpowiedź na tę operację zawiera następujące nagłówki. Odpowiedź może również zawierać dodatkowe standardowe nagłówki HTTP. Wszystkie nagłówki standardowe są zgodne ze specyfikacją protokołu HTTP/1.1.

Nagłówek odpowiedzi Opis
Content-Type Określa application/xml jako typ zawartości.
Content-Length Określa rozmiar zwracanego dokumentu XML w bajtach.
x-ms-request-id Jednoznacznie identyfikuje wykonane żądanie. Można go użyć do rozwiązywania problemów z żądaniem. Aby uzyskać więcej informacji, zobacz Rozwiązywanie problemów z operacjami interfejsu API.
x-ms-version Wskazuje wersję Azure Blob Storage, która została użyta do wykonania żądania.
Date Wartość daty/godziny UTC wskazująca godzinę, w której usługa wysłała odpowiedź.
x-ms-client-request-id Może służyć do rozwiązywania problemów z żądaniami i odpowiadającymi im odpowiedziami. Wartość tego nagłówka jest równa wartości x-ms-client-request-id nagłówka, jeśli znajduje się w żądaniu, a wartość wynosi co najwyżej 1024 widoczne znaki ASCII. x-ms-client-request-id Jeśli nagłówek nie znajduje się w żądaniu, ten nagłówek nie będzie obecny w odpowiedzi.

Treść odpowiedzi

W wersji 2020-04-08 i nowszych tagi pasujących obiektów blob są hermetyzowane w elemecie Tags . Format treści odpowiedzi jest następujący:

<?xml version="1.0" encoding="utf-8"?>  
<EnumerationResults ServiceEndpoint=http://myaccount.blob.core.windows.net/>  
  <Where>string-value</Where>  
  <Blobs>  
    <Blob>  
      <Name>blob-name</Name>  
      <ContainerName>container-name</ContainerName>  
      <Tags>
        <TagSet>
          <Tag>
            <Key>matching-tag-name1</Key>
            <Value>matching-tag-value1</Value>
          </Tag>
          <Tag>
            <Key>matching-tag-name2</Key>
            <Value>matching-tag-value2</Value>
          </Tag>
        </TagSet>
      </Tags> 
    </Blob>  
  </Blobs>  
  <NextMarker />  
</EnumerationResults>

Treść odpowiedzi jest dobrze sformułowanym dokumentem XML UTF-8.

Autoryzacja

Autoryzacja jest wymagana podczas wywoływania dowolnej operacji dostępu do danych w usłudze Azure Storage. Możesz autoryzować operację zgodnie z Find Blobs by Tags poniższym opisem.

Usługa Azure Storage obsługuje używanie Tożsamość Microsoft Entra do autoryzacji żądań do danych obiektów blob. Za pomocą Tożsamość Microsoft Entra możesz użyć kontroli dostępu opartej na rolach (RBAC) platformy Azure, aby udzielić uprawnień podmiotowi zabezpieczeń. Podmiot zabezpieczeń może być użytkownikiem, grupą, jednostką usługi aplikacji lub tożsamością zarządzaną platformy Azure. Podmiot zabezpieczeń jest uwierzytelniany przez Tożsamość Microsoft Entra w celu zwrócenia tokenu OAuth 2.0. Token może następnie służyć do autoryzowania żądania względem usługi Blob Service.

Aby dowiedzieć się więcej na temat autoryzacji przy użyciu Tożsamość Microsoft Entra, zobacz Autoryzowanie dostępu do obiektów blob przy użyciu Tożsamość Microsoft Entra.

Uprawnienia

Poniżej wymieniono akcję RBAC niezbędną do wywołania Find Blobs by Tags operacji przez użytkownika, grupę lub jednostkę usługi Microsoft Entra oraz najmniej uprzywilejowaną wbudowaną rolę RBAC platformy Azure, która obejmuje tę akcję:

Aby dowiedzieć się więcej na temat przypisywania ról przy użyciu kontroli dostępu opartej na rolach platformy Azure, zobacz Przypisywanie roli platformy Azure w celu uzyskania dostępu do danych obiektów blob.

Uwagi

Operacja jest obsługiwana Find Blobs by Tags w interfejsie API REST w wersji 2019-12-12 lub nowszej.

W przypadku kont z włączoną hierarchiczną przestrzenią nazw operacja nie jest obsługiwana, Find Blobs by Tags ponieważ tagi obiektów blob nie są obsługiwane dla hierarchicznych kont przestrzeni nazw.

Indeks pomocniczy, który Find Blobs by Tags używa, jest ostatecznie spójny. Aktualizacje do tagów obiektów blob za pośrednictwem Set Blob Tags może nie być natychmiast widoczne dla Find Blobs by Tags operacji.

Konstruowanie wyrażenia wyszukiwania

Parametr where URI znajduje obiekty blob na koncie magazynu, których tagi są zgodne z wyrażeniem. Wyrażenie musi zostać obliczone, aby true obiekt blob został zwrócony w zestawie wyników.

Usługa magazynu obsługuje podzestaw gramatyki klauzuli SQL WHERE ANSI dla wartości parametru where=<expression> zapytania. Usługa magazynu obsługuje następujące operatory:

Operator Opis Przykład
= Równe &where=Status = 'In Progress'
> Większe niż &where=LastModified > '2018-06-18 20:51:26Z'
>= Większe niż lub równe &where=Priority >= '05'
< Mniejsze niż &where=Age < '032'
<= Mniejsze niż lub równe &where=Reviewer <= 'Smith'
AND Logiczne i &where=Name > 'C' AND Name < 'D'
&where=Age > '032' AND Age < '100'
@container Określanie kontenera &where=@container='mycontainer' AND Name = 'C'

Uwaga

Wartość parametru where URI musi być poprawnie zakodowana w identyfikatorze URI (w tym spacjami i operatorami). Powyższe przykłady pomijają tę wartość w celu czytelności.

Wszystkie wartości tagów to ciągi. Obsługiwane operatory relacyjne binarne używają sortowania leksykograficznego wartości tagów. Aby obsługiwać typy danych innych niż ciągi, w tym liczby i daty, należy użyć odpowiedniego formatowania dopełniania i sortowania. Wartości tagów muszą być ujęte w pojedynczy cudzysłów.

Jeśli nazwy tagów są zwykłymi identyfikatorami SQL, mogą być obecne bez ucieczki. Jeśli zawierają znaki specjalne, muszą być rozdzielane podwójnym cudzysłowem (na przykład "TagName" = TagValue). Zalecamy, aby zawsze ująć nazwy tagów w podwójny cudzysłów.

Usługa magazynu odrzuci każde żądanie zawierające nieprawidłowe wyrażenie z kodem błędu 400 (nieprawidłowe żądanie).

Rozliczenia

Żądania cenowe mogą pochodzić od klientów korzystających z interfejsów API usługi Blob Storage bezpośrednio za pośrednictwem interfejsu API REST usługi Blob Storage lub biblioteki klienta usługi Azure Storage. Te żądania naliczają opłaty za transakcję. Typ transakcji wpływa na sposób naliczania opłat za konto. Na przykład transakcje odczytu są naliczane do innej kategorii rozliczeniowej niż transakcje zapisu. W poniższej tabeli przedstawiono kategorię rozliczeń dla Find Blobs by Tags żądań na podstawie typu konta magazynu:

Operacja Typ konta magazynu Kategoria rozliczeń
Znajdowanie obiektów blob według tagów Blokowy obiekt blob w warstwie Premium
Standardowa ogólnego przeznaczenia, wersja 2
Standardowa ogólnego przeznaczenia, wersja 1		 Wyświetlanie listy i tworzenie operacji kontenera

Aby dowiedzieć się więcej o cenach dla określonej kategorii rozliczeń, zobacz Azure Blob Storage Cennik.

Zobacz też

Zarządzanie danymi Azure Blob Storage i znajdowanie ich za pomocą tagów indeksów obiektów blob
Autoryzowanie żądań do usługi Azure Storage
Kody stanu i błędów
Kody błędów usługi Blob Storage