Dołączanie bloku z adresu URL
Operacja Append Block From URL zatwierdza nowy blok danych na końcu istniejącego uzupełnionego obiektu blob.
Operacja Append Block From URL jest dozwolona tylko wtedy, gdy obiekt blob został utworzony z ustawioną wartością x-ms-blob-typeAppendBlob.
Append Block From URL program jest obsługiwany tylko w wersji 2018-11-09 lub nowszej.
Żądanie
Żądanie można skonstruować Append Block From URL w następujący sposób. Zalecane jest użycie protokołu HTTPS. Zastąp ciąg myaccount nazwą konta magazynu.
| IDENTYFIKATOR URI żądania PUT | Wersja PROTOKOŁU HTTP |
|---|---|
https://myaccount.blob.core.windows.net/mycontainer/myblob?comp=appendblock |
HTTP/1.1 |
Podczas wysyłania żądania względem emulowanej usługi magazynu określ nazwę hosta emulatora i Azure Blob Storage port jako 127.0.0.1:10000, a następnie nazwę emulowanego konta magazynu.
| IDENTYFIKATOR URI żądania PUT | Wersja PROTOKOŁU HTTP |
|---|---|
http://127.0.0.1:10000/devstoreaccount1/mycontainer/myblob?comp=appendblock |
HTTP/1.1 |
Aby uzyskać więcej informacji, zobacz Use the Azurite emulator for local Azure Storage development (Używanie emulatora Azurite do lokalnego programowania w usłudze Azure Storage).
Parametry identyfikatora URI
| Parametr | Opis |
|---|---|
timeout |
Opcjonalny. Parametr limitu czasu jest wyrażony 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ń. Określa wersję operacji do użycia dla tego żądania. Aby uzyskać więcej informacji, zobacz Przechowywanie wersji usług Azure Storage. |
Content-Length |
Wymagane. Określa liczbę bajtów przesyłanych w treści żądania. Wartość tego nagłówka musi być ustawiona na zero. Jeśli długość nie jest równa zero, operacja zakończy się niepowodzeniem z kodem błędu 400 (nieprawidłowe żądanie). |
x-ms-copy-source:name |
Wymagane. Określa adres URL źródłowego obiektu blob. Wartość może być adresem URL o długości do 2 KiB, który określa obiekt blob. Wartość powinna być zakodowana w adresie URL, tak jak w identyfikatorze URI żądania. Źródłowy obiekt blob musi być publiczny lub musi być autoryzowany za pośrednictwem sygnatury dostępu współdzielonego. Jeśli źródłowy obiekt blob jest publiczny, do wykonania operacji nie jest wymagana autoryzacja. Oto kilka przykładów adresów URL obiektów źródłowych:https://myaccount.blob.core.windows.net/mycontainer/myblobhttps://myaccount.blob.core.windows.net/mycontainer/myblob?snapshot=<DateTime>https://myaccount.blob.core.windows.net/mycontainer/myblob?versionid=<DateTime> |
x-ms-copy-source-authorization: <scheme> <signature> |
Opcjonalny. Określa schemat autoryzacji i podpis dla źródła kopiowania. Aby uzyskać więcej informacji, zobacz Autoryzowanie żądań do usługi Azure Storage. Tylko program nośny schematu jest obsługiwany w przypadku Tożsamość Microsoft Entra. Ten nagłówek jest obsługiwany w wersji 2020-10-02 lub nowszej. |
x-ms-source-range |
Opcjonalny. Przekazuje tylko bajty obiektu blob w źródłowym adresie URL w określonym zakresie. Jeśli nie zostanie określona, cała zawartość źródłowego obiektu blob zostanie przekazana jako pojedynczy blok dołączania. Aby uzyskać więcej informacji, zobacz Określanie nagłówka zakresu dla operacji usługi Blob Storage . |
x-ms-source-content-md5 |
Opcjonalny. Skrót MD5 zawartości bloku dołączania z identyfikatora URI. Ten skrót służy do weryfikowania integralności bloku dołączania podczas transportu danych z identyfikatora URI. Po określeniu tego nagłówka usługa magazynu porównuje skrót zawartości, która dotarła ze źródła kopiowania z tą wartością nagłówka. Należy pamiętać, że ten skrót MD5 nie jest przechowywany w obiekcie blob. Jeśli dwa skróty nie są zgodne, operacja kończy się niepowodzeniem z kodem błędu 400 (Nieprawidłowe żądanie). |
x-ms-source-content-crc64 |
Opcjonalny. Skrót CRC64 zawartości bloku dołączania z identyfikatora URI. Ten skrót służy do weryfikowania integralności bloku dołączania podczas transportu danych z identyfikatora URI. Po określeniu tego nagłówka usługa magazynu porównuje skrót zawartości, która dotarła ze źródła kopiowania z tą wartością nagłówka. Należy pamiętać, że ten skrót CRC64 nie jest przechowywany w obiekcie blob. Jeśli dwa skróty nie są zgodne, operacja kończy się niepowodzeniem z kodem błędu 400 (Nieprawidłowe żądanie). Jeśli istnieją zarówno x-ms-source-content-md5 nagłówki, jak i x-ms-source-content-crc64 żądanie kończy się niepowodzeniem z błędem 400 (nieprawidłowe żądanie).Ten nagłówek jest obsługiwany w wersji 2019-02-02 lub nowszej. |
x-ms-encryption-scope |
Opcjonalny. Wskazuje zakres szyfrowania używany do szyfrowania zawartości źródłowej. Ten nagłówek jest obsługiwany w wersji 2019-02-02 lub nowszej. |
x-ms-lease-id:<ID> |
Wymagane, jeśli obiekt blob ma aktywną dzierżawę. Aby wykonać tę operację na obiekcie blob z aktywną dzierżawą, określ prawidłowy identyfikator dzierżawy dla tego nagłówka. |
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. Aby uzyskać więcej informacji, zobacz Monitorowanie Azure Blob Storage. |
x-ms-blob-condition-maxsize |
Opcjonalny nagłówek warunkowy. Maksymalna długość bajtów dozwolona dla uzupełnialnych obiektów blob.
Append Block From URL Jeśli operacja spowoduje przekroczenie tego limitu obiektu blob lub jeśli rozmiar obiektu blob jest już większy niż wartość określona w tym nagłówku, żądanie kończy się niepowodzeniem z wartością 412 (Niepowodzenie warunku wstępnego). |
x-ms-blob-condition-appendpos |
Opcjonalny nagłówek warunkowy, używany tylko dla Append Block from URL operacji. Liczba wskazująca przesunięcie bajtów do porównania.
Append Block from URL kończy się powodzeniem tylko wtedy, gdy pozycja dołączania jest równa tej liczbie. Jeśli tak nie jest, żądanie zakończy się niepowodzeniem z błędem 412 (Niepowodzenie warunku wstępnego). |
Ta operacja obsługuje użycie dodatkowych, warunkowych nagłówków, aby upewnić się, że interfejs API zakończy się powodzeniem tylko wtedy, gdy zostanie spełniony określony warunek. Aby uzyskać więcej informacji, zobacz Określanie nagłówków warunkowych dla operacji usługi Blob Storage.
Nagłówki żądań (klucze szyfrowania dostarczone przez klienta)
Począwszy od wersji 2019-02-02, można określić następujące nagłówki na żądanie szyfrowania obiektu blob przy użyciu klucza dostarczonego przez klienta. Szyfrowanie przy użyciu klucza dostarczonego przez klienta (i odpowiedniego zestawu nagłówków) jest opcjonalne.
| Nagłówek żądania | Opis |
|---|---|
x-ms-encryption-key |
Wymagane. Klucz szyfrowania AES-256 zakodowany w formacie Base64. |
x-ms-encryption-key-sha256 |
Wymagane. Skrót SHA256 zakodowany w formacie Base64 klucza szyfrowania. |
x-ms-encryption-algorithm: AES256 |
Wymagane. Określa algorytm do użycia do szyfrowania. Wartość tego nagłówka musi mieć wartość AES256. |
Treść żądania
Treść żądania zawiera zawartość bloku.
Przykładowe żądanie
Request Syntax:
PUT https://myaccount.blob.core.windows.net/mycontainer/myblob?comp=appendblock HTTP/1.1
Request Headers:
x-ms-version: 2018-11-09
x-ms-date: <date>
x-ms-copy-source: https://myaccount.blob.core.windows.net/mycontainer/myblob
x-ms-source-range: bytes=0-65535
x-ms-blob-condition-appendpos: 2097152
x-ms-blob-condition-maxsize: 4194304
Authorization: SharedKey myaccount:J4ma1VuFnlJ7yfk/Gu1GxzbfdJloYmBPWlfhZ/xn7GI=
Content-Length: 0
If-Match: "0x8CB172A360EC34B"
Reakcja
Odpowiedź zawiera kod stanu HTTP i zestaw nagłówków odpowiedzi.
Kod stanu
Operacja zakończona powodzeniem zwraca kod stanu 201 (utworzono). 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 |
|---|---|
Etag |
Element ETag zawiera wartość w cudzysłowie. Klient używa wartości do wykonywania operacji warunkowych PUT przy użyciu nagłówka If-Match żądania. |
Last-Modified |
Data/godzina ostatniej modyfikacji obiektu blob. Format daty jest zgodny z RFC 1123. Aby uzyskać więcej informacji, zobacz Reprezentacja wartości daty i godziny w nagłówkach. Każda operacja zapisu w obiekcie blob (w tym aktualizacje metadanych lub właściwości obiektu blob) zmienia czas ostatniej modyfikacji obiektu blob. |
Content-MD5 |
Ten nagłówek jest zwracany, aby klient mógł sprawdzić integralność zawartości komunikatu. Usługa Blob Storage oblicza wartość tego nagłówka. Niekoniecznie jest to ta sama wartość określona w nagłówkach żądania. W przypadku wersji 2019-02-02 lub nowszej ten nagłówek jest zwracany tylko wtedy, gdy żądanie ma ten nagłówek. |
x-ms-content-crc64 |
W wersji 2019-02-02 lub nowszej. Ten nagłówek jest zwracany, aby klient mógł sprawdzić integralność zawartości komunikatu. Usługa Blob Storage oblicza wartość tego nagłówka. Niekoniecznie jest to ta sama wartość określona w nagłówkach żądania. Ten nagłówek jest zwracany, gdy x-ms-source-content-md5 nagłówek nie znajduje się w żądaniu. |
x-ms-request-id |
Ten nagłówek jednoznacznie identyfikuje wykonane żądanie i może służyć do rozwiązywania problemów z żądaniem. |
x-ms-version |
Wskazuje wersję usługi Blob Storage używaną do uruchomienia żądania. Ten nagłówek jest zwracany dla żądań wysyłanych w wersji 2009-09-19 lub nowszej. |
Date |
Wartość daty/godziny UTC wygenerowana przez usługę, która wskazuje godzinę, w której zainicjowano odpowiedź. |
x-ms-blob-append-offset |
Ten nagłówek odpowiedzi jest zwracany tylko w przypadku operacji dołączania. Zwraca przesunięcie, przy którym blok został zatwierdzony w bajtach. |
x-ms-blob-committed-block-count |
Liczba zatwierdzonych bloków znajdujących się w obiekcie blob. Można to użyć do kontrolowania liczby dołączań, które można wykonać. |
x-ms-request-server-encrypted: true/false |
Wersja 2015-12-11 lub nowsza. Wartość tego nagłówka jest ustawiana na true wartość , jeśli zawartość żądania zostanie pomyślnie zaszyfrowana przy użyciu określonego algorytmu. W przeciwnym razie wartość jest ustawiona na false. |
x-ms-encryption-key-sha256 |
Wersja 2019-02-02 lub nowsza. Ten nagłówek jest zwracany, jeśli żądanie użyło klucza dostarczonego przez klienta do szyfrowania. Klient może następnie upewnić się, że zawartość żądania została pomyślnie zaszyfrowana przy użyciu podanego klucza. |
x-ms-encryption-scope |
Wersja 2019-02-02 lub nowsza. Ten nagłówek jest zwracany, jeśli żądanie użyło zakresu szyfrowania. Klient może następnie upewnić się, że zawartość żądania została pomyślnie zaszyfrowana przy użyciu zakresu szyfrowania. |
Przykładowa odpowiedź
Response Status:
HTTP/1.1 201 Created
Response Headers:
Transfer-Encoding: chunked
x-ms-content-crc64: 77uWZTolTHU
Date: <date>
Server: Windows-Azure-Blob/1.0 Microsoft-HTTPAPI/2.0
x-ms-blob-append-offset: 2097152
x-ms-blob-committed–block-count: 1000
Autoryzacja
Autoryzacja jest wymagana podczas wywoływania dowolnej operacji dostępu do danych w usłudze Azure Storage. Możesz autoryzować operację zgodnie z Append Block From URL poniższym opisem.
Szczegóły autoryzacji w tej sekcji dotyczą miejsca docelowego kopiowania. Aby uzyskać więcej informacji na temat autoryzacji źródła kopiowania, zobacz szczegóły nagłówka x-ms-copy-sourceżądania .
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ółdzielonego.
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ą do Microsoft Entra użytkownika, grupy, tożsamości zarządzanej lub jednostki usługi w celu wywołania Append Block From URL operacji oraz najmniej uprzywilejowanej wbudowanej roli RBAC platformy Azure, która obejmuje tę akcję:
- Akcja RBAC platformy Azure:Microsoft.Storage/storageAccounts/blobServices/containers/blobs/add/action lub Microsoft.Storage/storageAccounts/blobServices/containers/blobs/write
- Rola wbudowana z najmniejszymi uprawnieniami:Współautor danych obiektu blob usługi Storage
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
Append Block From URL przekazuje blok na końcu istniejącego uzupełnialnych obiektów blob. Blok danych jest natychmiast dostępny po pomyślnym wywołaniu na serwerze. Dozwolone jest maksymalnie 50 000 dołączań dla każdego uzupełnialnych obiektów blob, gdzie. Każdy blok może mieć inny rozmiar.
W poniższej tabeli opisano maksymalne dozwolone rozmiary bloków i obiektów blob według wersji usługi:
| Wersja usługi | Maksymalny rozmiar bloku (za pośrednictwem Append Block From URL) |
Maksymalny rozmiar obiektu blob |
|---|---|---|
| Wersja 2022-11-02 lub nowsza | 100 MiB (wersja zapoznawcza) | Około 4,75 TiB (100 MiB × 50 000 bloków) |
| Wersje starsze niż 2022-11-02 | 4 MiB | Około 195 gibibajtów (GiB) (4 MiB × 50 000 bloków) |
W wersji 2020-10-02 lub nowszej autoryzacja Tożsamość Microsoft Entra jest obsługiwana dla źródła operacji kopiowania.
Append Block From URL kończy się powodzeniem tylko wtedy, gdy obiekt blob już istnieje.
Obiekty blob przekazane przy użyciu polecenia Append Block From URL nie uwidaczniają identyfikatorów bloków, więc nie można wywołać funkcji Pobierz listę bloków względem uzupełnialnych obiektów blob. Spowoduje to wystąpienie błędu.
W żądaniu można określić następujące opcjonalne nagłówki warunkowe:
x-ms-blob-condition-appendpos: Ten nagłówek można ustawić na przesunięcie bajtów, przy którym klient oczekuje dołączenia bloku. Żądanie powiedzie się tylko wtedy, gdy bieżące przesunięcie pasuje do określonego przez klienta. W przeciwnym razie żądanie kończy się niepowodzeniem z kodem błędu 412 (Niepowodzenie warunku wstępnego).Klienci korzystający z pojedynczego modułu zapisywania mogą używać tego nagłówka, aby określić, czy
Append Block From URLoperacja zakończyła się pomyślnie, pomimo awarii sieci.x-ms-blob-condition-maxsize: Klienci mogą używać tego nagłówka, aby upewnić się, że operacje dołączania nie zwiększają rozmiaru obiektu blob poza oczekiwany maksymalny rozmiar w bajtach. Jeśli warunek zakończy się niepowodzeniem, żądanie zakończy się niepowodzeniem z kodem błędu 412 (Niepowodzenie warunku wstępnego).
Jeśli spróbujesz przekazać blok większy niż dozwolony rozmiar, usługa zwróci kod błędu HTTP 413 (Zbyt duża jednostka żądania). Usługa zwraca również dodatkowe informacje o błędzie w odpowiedzi, w tym maksymalny rozmiar bloku dozwolony w bajtach. Jeśli spróbujesz przekazać więcej niż 50 000 bloków, usługa zwróci kod błędu 409 (Konflikt).
Jeśli obiekt blob ma aktywną dzierżawę, klient musi określić prawidłowy identyfikator dzierżawy w żądaniu, aby zapisać blok w obiekcie blob. Jeśli klient nie określi identyfikatora dzierżawy lub określi nieprawidłowy identyfikator dzierżawy, usługa Blob Storage zwraca kod błędu 412 (Niepowodzenie warunku wstępnego). Jeśli klient określa identyfikator dzierżawy, ale obiekt blob nie ma aktywnej dzierżawy, usługa zwraca kod błędu 412.
Jeśli wywołasz Append Block From URL istniejący blokowy obiekt blob lub stronicowy obiekt blob, usługa zwróci kod błędu 409 (Konflikt). Jeśli wywołasz Append Block From URL obiekt blob nieistniejący, usługa zwróci kod błędu 404 (Nie znaleziono).
Unikaj zduplikowanych lub opóźnionych dołączań
W jednym scenariuszu zapisywania klient może uniknąć zduplikowanych dołączań lub opóźnionych zapisów przy użyciu x-ms-blob-condition-appendpos nagłówka warunkowego w celu sprawdzenia bieżącego przesunięcia. Klient może również uniknąć duplikatów lub opóźnień, sprawdzając ETag warunkowo przy użyciu polecenia If-Match.
W scenariuszu z wieloma składnikami zapisywania każdy klient może używać nagłówków warunkowych. Może to nie być optymalne dla wydajności. W przypadku największej przepływności dołączania współbieżnego aplikacje powinny obsługiwać nadmiarowe dołączania i opóźnione dołączania w warstwie aplikacji. Na przykład aplikacje mogą dodawać epoki lub numery sekwencji w dołączanych danych.
Aby dowiedzieć się więcej o cenach dla określonej kategorii rozliczeniowej, zobacz Azure Blob Storage Cennik.
Rozliczenia
Żądania cen 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 w innej kategorii rozliczeniowej niż transakcje zapisu. W poniższej tabeli przedstawiono kategorię rozliczeń dla Append Block From URL żądań na podstawie typu konta magazynu:
| Operacja | Typ konta magazynu | Kategoria rozliczeń |
|---|---|---|
| Dołączanie bloku z adresu URL (konto docelowe1) | Blokowy obiekt blob w warstwie Premium Standardowa ogólnego przeznaczenia, wersja 2 Standardowa ogólnego przeznaczenia, wersja 1 |
Operacje zapisu |
| Dołączanie bloku z adresu URL (konto źródłowe2) | Blokowy obiekt blob w warstwie Premium Standardowa ogólnego przeznaczenia, wersja 2 Standardowa ogólnego przeznaczenia, wersja 1 |
Operacje odczytu |
1Konto docelowe jest obciążane opłatą za jedną transakcję w celu zainicjowania zapisu.
2Konto źródłowe powoduje naliczenie jednej transakcji dla każdego żądania odczytu do źródła.