Udostępnij za pośrednictwem

Blob Batch

  • Artykuł

Operacja Blob Batch umożliwia osadzanie wielu wywołań interfejsu API w jednym żądaniu HTTP. Ten interfejs API obsługuje dwa typy podkwestni: Ustaw warstwę obiektu blob dla blokowych obiektów blob i Usuń obiekt blob. Odpowiedź zwrócona przez serwer dla żądania wsadowego zawiera wyniki dla każdego podrzędnego żądania w partii. Żądanie wsadowe i odpowiedź używają składni OData specyfikacji przetwarzania wsadowego z modyfikacjami semantyki. Ten interfejs API jest dostępny od wersji 2018-11-09.

Żądanie

Żądanie można skonstruować Blob Batch w następujący sposób. Zalecane jest użycie protokołu HTTPS. Zastąp ciąg myaccount nazwą konta magazynu.

Metoda Identyfikator URI żądania Wersja PROTOKOŁU HTTP
POST https://myaccount.blob.core.windows.net/?comp=batch

https://myaccount.blob.core.windows.net/containername?restype=container&comp=batch		 HTTP/1.1

Parametry identyfikatora URI

Dla identyfikatora URI żądania można określić następujące dodatkowe parametry.

Parametr Opis
timeout Opcjonalny. Parametr limitu czasu jest wyrażony w sekundach z maksymalną wartością 120 sekund. Aby uzyskać więcej informacji, zobacz Ustawianie limitów czasu dla operacji usługi Blob Storage.
restype Opcjonalnie, wersja 2020-04-08 i nowsze. Jedyną wartością obsługiwaną dla parametru restype jest container. Po określeniu tego parametru identyfikator URI musi zawierać nazwę kontenera. Wszystkie podwyżki muszą być ograniczone do tego samego kontenera.

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 magazynu 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ń. Określa wersję operacji do użycia dla tego żądania. Ta wersja będzie używana dla wszystkich podwsieci. Aby uzyskać więcej informacji, zobacz Przechowywanie wersji dla usług Azure Storage.
Content-Length Wymagane. Długość żądania.
Content-Type Wymagane. Wartość tego nagłówka musi mieć multipart/mixedwartość , z granicą wsadową. Przykładowa wartość nagłówka: multipart/mixed; boundary=batch_a81786c8-e301-4e42-a729-a32ca24ae252.
x-ms-client-request-id Opcjonalny. Zapewnia nieprzezroczystą wartość wygenerowaną przez klienta z limitem znaków 1-kibibyte (KiB) rejestrowanym w dziennikach podczas konfigurowania rejestrowania. Zdecydowanie zalecamy używanie tego nagłówka do korelowania działań po stronie klienta z żądaniami odbieranymi przez serwer. Aby uzyskać więcej informacji, zobacz Monitorowanie Azure Blob Storage.

Treść żądania

Treść żądania dla partii obiektów blob zawiera listę wszystkich podkwestni. Format używa składni specyfikacji wsadowej OData z modyfikacjami semantyki.

Treść żądania rozpoczyna się od granicy wsadowej, a następnie dwóch obowiązkowych nagłówków: Content-Type nagłówka z wartością , i Content-Transfer-Encoding nagłówka o wartości binaryapplication/http. Następuje po nim opcjonalny Content-ID nagłówek z wartością ciągu do śledzenia każdego z podwzestników. Odpowiedź zawiera Content-ID nagłówek dla każdej odpowiedniej odpowiedzi żądania podrzędnego do użycia do śledzenia.

Te nagłówki żądań są następnie obowiązkowym pustym wierszem, a następnie definicją każdego podwsądania. Treść każdego żądania podrzędnego jest kompletnym żądaniem HTTP z czasownikiem, adresem URL, nagłówkami i treścią wymaganą dla żądania. Zwróć uwagę na następujące zastrzeżenia:

  • Podwsieci nie powinny mieć parametru x-ms-version header. Wszystkie żądania podrzędne są uruchamiane z wersją żądania wsadowego najwyższego poziomu.
  • Adres URL podzapytania powinien mieć tylko ścieżkę adresu URL (bez hosta).
  • Każde żądanie wsadowe obsługuje maksymalnie 256 żądań podrzędnych.
  • Wszystkie podwyżki muszą być tego samego typu żądania.
  • Każde żądanie podrzędne jest autoryzowane oddzielnie, z podanymi informacjami w podkwestionie.
  • Każdy wiersz w treści żądania powinien kończyć się \r\n znakami.

Przykładowe żądanie

POST http://account.blob.core.windows.net/?comp=batch HTTP/1.1 
Content-Type: multipart/mixed; boundary=batch_357de4f7-6d0b-4e02-8cd2-6361411a9525 
x-ms-version: 2018-11-09 
Authorization: SharedKey account:QvaoYDQ+0VcaA/hKFjUmQmIxXv2RT3XwwTsOTHL39HI=
Host: 127.0.0.1:10000 
Content-Length: 1569 

--batch_357de4f7-6d0b-4e02-8cd2-6361411a9525 
Content-Type: application/http 
Content-Transfer-Encoding: binary 
Content-ID: 0 

DELETE /container0/blob0 HTTP/1.1 
x-ms-date: Thu, 14 Jun 2018 16:46:54 GMT 
Authorization: SharedKey account:G4jjBXA7LI/RnWKIOQ8i9xH4p76pAQ+4Fs4R1VxasaE= 
Content-Length: 0 

--batch_357de4f7-6d0b-4e02-8cd2-6361411a9525 
Content-Type: application/http 
Content-Transfer-Encoding: binary 
Content-ID: 1 

DELETE /container1/blob1 HTTP/1.1 
x-ms-date: Thu, 14 Jun 2018 16:46:54 GMT 
Authorization: SharedKey account:IvCoYDQ+0VcaA/hKFjUmQmIxXv2RT3XwwTsOTHL39HI= 
Content-Length: 0 

--batch_357de4f7-6d0b-4e02-8cd2-6361411a9525 
Content-Type: application/http 
Content-Transfer-Encoding: binary 
Content-ID: 2 

DELETE /container2/blob2 HTTP/1.1 
x-ms-date: Thu, 14 Jun 2018 16:46:54 GMT 
Authorization: SharedKey account:S37N2JTjcmOQVLHLbDmp2johz+KpTJvKhbVc4M7+UqI= 
Content-Length: 0 

--batch_357de4f7-6d0b-4e02-8cd2-6361411a9525--

Reakcja

Odpowiedź zawiera kod stanu HTTP i zestaw nagłówków odpowiedzi dla żądania wsadowego najwyższego poziomu. Odpowiedź zawiera również informacje o odpowiedzi dla wszystkich jego podkwestni.

Treść odpowiedzi

Odpowiedź wsadowa jest odpowiedzią zawierającą multipart/mixed odpowiedź dla każdego podwsądu. Odpowiedź jest fragmentowana. Każda pododpowiedzi rozpoczyna się od nagłówka Content-Type: application/http . Nagłówek Content-ID jest następujący, jeśli został podany w żądaniu. Następuje po nim kod stanu odpowiedzi HTTP i nagłówki odpowiedzi dla każdego podwzestu.

Aby uzyskać informacje na temat nagłówków zwracanych przez każde podzadanie, zobacz dokumentację operacji Usuwania obiektu blob i Ustawianie warstwy obiektu blob .

Przykładowa odpowiedź

HTTP/1.1 202 Accepted 
Transfer-Encoding: chunked 
Content-Type: multipart/mixed; boundary=batchresponse_66925647-d0cb-4109-b6d3-28efe3e1e5ed 
x-ms-request-id: 778fdc83-801e-0000-62ff-033467000000 
x-ms-version: 2018-11-09 

409
--batchresponse_66925647-d0cb-4109-b6d3-28efe3e1e5ed 
Content-Type: application/http 
Content-ID: 0 

HTTP/1.1 202 Accepted 
x-ms-delete-type-permanent: true
x-ms-request-id: 778fdc83-801e-0000-62ff-0334671e284f 
x-ms-version: 2018-11-09 

--batchresponse_66925647-d0cb-4109-b6d3-28efe3e1e5ed 
Content-Type: application/http 
Content-ID: 1 

HTTP/1.1 202 Accepted 
x-ms-delete-type-permanent: true
x-ms-request-id: 778fdc83-801e-0000-62ff-0334671e2851 
x-ms-version: 2018-11-09 

--batchresponse_66925647-d0cb-4109-b6d3-28efe3e1e5ed 
Content-Type: application/http 
Content-ID: 2 

HTTP/1.1 404 The specified blob does not exist. 
x-ms-error-code: BlobNotFound 
x-ms-request-id: 778fdc83-801e-0000-62ff-0334671e2852 
x-ms-version: 2018-11-09 
Content-Length: 216 
Content-Type: application/xml 

<?xml version="1.0" encoding="utf-8"?> 
<Error><Code>BlobNotFound</Code><Message>The specified blob does not exist. 
RequestId:778fdc83-801e-0000-62ff-0334671e2852 
Time:2018-06-14T16:46:54.6040685Z</Message></Error> 
--batchresponse_66925647-d0cb-4109-b6d3-28efe3e1e5ed-- 
0

Kod stanu

Jeśli żądanie wsadowe jest poprawnie sformułowane i autoryzowane, operacja zwraca kod stanu 202 (Zaakceptowano). Każde podzadanie ma własną odpowiedź w zależności od wyniku operacji. Stan żądania podrzędnego jest zwracany w treści odpowiedzi.

Aby uzyskać więcej informacji, zobacz Status and error codes (Kody stanu i 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 standardowe nagłówki są zgodne ze specyfikacją protokołu HTTP/1.1.

Autoryzacja

Po restype=container pominięciu należy autoryzować nadrzędne żądanie wsadowe przy użyciu klucza współużytkowanego. Możesz użyć klucza dostępu konta, sygnatury dostępu współdzielonego konta lub Microsoft Entra. Szczegóły dotyczące określonych mechanizmów autoryzacji pokazanych poniżej.

Po restype=container dołączeniu żądania można autoryzować nadrzędne żądanie wsadowe za pomocą klucza współużytkowanego lub Microsoft Entra. Możesz również autoryzować przy użyciu sygnatury dostępu współdzielonego podpisanego przez jeden z tych mechanizmów autoryzacji. Szczegóły dotyczące określonych mechanizmów autoryzacji pokazanych poniżej.

Każde żądanie podrzędne jest autoryzowane oddzielnie. Subrequest obsługuje te same mechanizmy autoryzacji, które obsługuje operacja, gdy nie jest częścią operacji wsadowej.

Ważne

Firma Microsoft zaleca używanie Tożsamość Microsoft Entra z tożsamościami zarządzanymi w celu autoryzowania żądań do usługi Azure Storage. Tożsamość Microsoft Entra zapewnia doskonałe zabezpieczenia i łatwość użycia w porównaniu z autoryzacją klucza wspólnego.

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 przedstawiono akcję RBAC niezbędną dla użytkownika Microsoft Entra, grupy, tożsamości zarządzanej lub jednostki usługi w celu utworzenia Blob Batch żądania nadrzędnego oraz najmniej uprzywilejowanej wbudowanej roli 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.

Rozliczenia

Blob Batch Żądanie REST jest liczone jako jedna transakcja, a każde pojedyncze podzbicie jest również liczone jako jedna transakcja. Aby dowiedzieć się więcej na temat rozliczeń dla poszczególnych podkwesti, zobacz dokumentację dotyczącą operacji Usuń obiekt blob i Ustawianie warstwy obiektów blob .

Żą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 żądania nadrzędnego Blob Batch na podstawie typu konta magazynu:

Operacja Typ konta magazynu Kategoria rozliczeń
Usługa Blob Batch (ustaw warstwę obiektu blob) Blokowy obiekt blob w warstwie Premium
Standardowa ogólnego przeznaczenia, wersja 2		 Inne operacje

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

Uwagi

Jedną z głównych zalet korzystania z żądania wsadowego jest zmniejszenie liczby połączeń, które klient musi otworzyć. Zwróć uwagę na następujące ograniczenia:

  • Obsługiwane podkwestnie w partii to Set Blob Tier (w przypadku blokowych obiektów blob) i Delete Blob.
  • W jednej partii obsługuje tylko maksymalnie 256 podkwesti. Rozmiar treści żądania wsadowego nie może przekraczać 4 MB.
  • Puste żądanie wsadowe kończy się niepowodzeniem z kodem 400 (nieprawidłowe żądanie).
  • Nie ma gwarancji dotyczących kolejności wykonywania podwystęg wsadowych.
  • Wykonywanie podzadań usługi Batch nie jest niepodzielne. Każde podzbięcie jest uruchamiane niezależnie.
  • Każde podzbicie musi być przeznaczone dla zasobu na tym samym koncie magazynu. Pojedyncze żądanie wsadowe nie obsługuje uruchamiania żądań z różnych kont magazynu.
  • Zagnieżdżona treść żądania nie jest obsługiwana.
  • Jeśli serwer nie może przeanalizować treści żądania, cała partia zakończy się niepowodzeniem i żadne żądanie nie zostanie uruchomione.
  • Należy pamiętać, że sygnatura dostępu współdzielonego jest jedynym typem sygnatury dostępu współdzielonego obsługiwanym przez Blob Batchusługę , gdy usługa Batch nie korzysta z usługi restype=container.

Określanie zakresu wszystkich podkwesti do określonego kontenera

Począwszy od wersji REST 2020-04-08, Blob Batch interfejs API obsługuje określanie zakresu podzadania do określonego kontenera. Gdy identyfikator URI żądania zawiera nazwę kontenera restype=container i parametr, każde podzbicie musi mieć zastosowanie do tego samego kontenera. Jeśli nazwa kontenera określona dla podkwestowania nie jest zgodna z nazwą kontenera podaną w identyfikatorze URI, usługa zwraca kod błędu 400 (Nieprawidłowe żądanie).

Wszystkie mechanizmy autoryzacji obsługiwane dla kontenera są prawidłowe dla Blob Batch operacji, która jest ograniczona do kontenera. Każde podzbicie wysyła nagłówek autoryzacji do usługi.

Zobacz też

Autoryzowanie żądań do stanu usługi Azure Storagei kodów błędów usługi Blob Storage kody błędówUstawianie limitów czasu dla operacji usługi Blob Storage