Udostępnij za pośrednictwem

Umieść blok z adresu URL

  • Artykuł

Operacja Put Block From URL tworzy nowy blok do zatwierdzenia w ramach obiektu blob, w którym zawartość jest odczytywana z adresu URL. Ten interfejs API jest dostępny w wersji 2018-03-28.

Żądanie

Żądanie można skonstruować Put Block From URL w następujący sposób. Zalecamy korzystanie z 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=block&blockid=id HTTP/1.1

Żądanie usługi magazynu emulowanego

Gdy wysyłasz żądanie względem emulowanej usługi magazynu, określ nazwę hosta emulatora i port usługi Blob 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=block&blockid=id 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
blockid Wymagane. Prawidłowa wartość ciągu Base64, która identyfikuje blok. Przed kodowaniem ciąg musi być mniejszy lub równy 64 bajtom w rozmiarze.

W przypadku określonego obiektu blob długość określonej wartości parametru blockid musi mieć ten sam rozmiar dla każdego bloku.

Uwaga: ciąg Base64 musi być zakodowany w adresie URL.
timeout Opcjonalny. Parametr jest wyrażony timeout w sekundach. Aby uzyskać więcej informacji, zobacz Ustawianie limitów czasu dla operacji usługi Blob Service.

Nagłówki żądań

Wymagane i opcjonalne nagłówki żądań zostały opisane w poniższej tabeli:

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 dla usług Azure Storage. W przypadku Put Block From URLprogramu wersja musi mieć wartość 2018-03-28 lub nowsza.
Content-Length Wymagane. Określa liczbę bajtów przesyłanych w treści żądania. Wartość tego nagłówka musi być ustawiona na 0. Jeśli długość nie jest 0, operacja kończy się niepowodzeniem z kodem stanu 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 kibibajtów (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 autoryzowany za pośrednictwem sygnatury dostępu współdzielonego. Jeśli źródłowy obiekt blob jest publiczny, do wykonania operacji nie jest wymagana żadna autoryzacja. Oto kilka przykładów źródłowych adresów URL obiektów:

- https://myaccount.blob.core.windows.net/mycontainer/myblob
- https://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 kopii. Aby uzyskać więcej informacji, zobacz Autoryzowanie żądań do usługi Azure Storage.
Tylko schemat elementu nośnego jest obsługiwany w przypadku Microsoft Entra.
Ten nagłówek jest obsługiwany w wersjach 2020-10-02 i nowszych.
x-ms-source-range Opcjonalny. Przekazuje tylko bajty obiektu blob w źródłowym adresie URL w określonym zakresie. Jeśli ten nagłówek nie zostanie określony, cała zawartość źródłowego obiektu blob zostanie przekazana jako pojedynczy blok. Aby uzyskać więcej informacji, zobacz Określanie nagłówka zakresu dla operacji usługi Blob Service.
x-ms-source-content-md5 Opcjonalny. Skrót MD5 zawartości bloku z identyfikatora URI. Ten skrót służy do weryfikowania integralności bloku 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 z kopii źródła z tą wartością nagłówka.

Uwaga: 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 z identyfikatora URI. Ten skrót służy do weryfikowania integralności bloku 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 z kopii źródła z tą wartością nagłówka.

Uwaga: 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 wersjach 2019-02-02 i nowszych.
x-ms-encryption-scope Opcjonalny. Wskazuje zakres szyfrowania używany do szyfrowania zawartości źródłowej. Ten nagłówek jest obsługiwany w wersjach 2019-02-02 i nowszych.
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. 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.

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 zaszyfrowania obiektu blob przy użyciu klucza dostarczonego przez klienta. Szyfrowanie przy użyciu klucza dostarczonego przez klienta (i odpowiadającego mu 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 na potrzeby szyfrowania. Wartość tego nagłówka musi mieć wartość AES256.

Treść żądania

Brak.

Przykładowe żądanie

Request Syntax:  
PUT https://myaccount.blob.core.windows.net/mycontainer/myblob?comp=block&blockid=AAAAAA%3D%3D HTTP/1.1  
  
Request Headers:  
x-ms-version: 2018-03-28  
x-ms-date: Sat, 31 Mar 2018 14:37:35 GMT    
Authorization: SharedKey myaccount:J4ma1VuFnlJ7yfk/Gu1GxzbfdJloYmBPWlfhZ/xn7GI=  
Content-Length: 0
x-ms-copy-source: https://myaccount.blob.core.windows.net/mycontainer/myblob
x-ms-source-range: bytes=0-499

Reakcja

Odpowiedź zawiera kod stanu HTTP i zestaw nagłówków odpowiedzi.

Kod stanu

Pomyślna operacja zwraca kod stanu 201 (Utworzony).

Aby uzyskać więcej informacji na temat kodów stanu, zobacz 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.

Nagłówek odpowiedzi Opis
Content-MD5 Zwrócone, aby klient mógł sprawdzić integralność zawartości komunikatu. Wartość tego nagłówka jest obliczana przez usługę Blob Storage. Nie musi być taka sama jak wartość określona w nagłówkach żądania. W przypadku wersji 2019-02-02 i nowszych ten nagłówek jest zwracany tylko wtedy, gdy żądanie ma ten nagłówek.
x-ms-content-crc64 W wersjach 2019-02-02 i nowszych. Zwrócone, aby klient mógł sprawdzić integralność zawartości komunikatu. Wartość tego nagłówka jest obliczana przez usługę Blob Storage. Nie musi być taka sama jak wartość określona w nagłówkach żądania.

Zwracany, gdy x-ms-source-content-md5 nagłówek nie jest obecny w żądaniu.
x-ms-request-id Unikatowo identyfikuje żądanie, które zostało wykonane, i 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 Wersja usługi Blob Storage, która została użyta do wykonania żądania.
Date Wartość daty/godziny UTC wygenerowana przez usługę, która wskazuje godzinę zainicjowania odpowiedzi.
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ść bloku została 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. Zwrócony, jeśli żądanie użyło klucza dostarczonego przez klienta do szyfrowania, aby klient mógł 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. Zwrócone, jeśli żądanie używa zakresu szyfrowania, aby klient mógł upewnić się, że zawartość żądania została pomyślnie zaszyfrowana przy użyciu zakresu szyfrowania.
x-ms-client-request-id Może służyć do rozwiązywania problemów z żądaniami i odpowiadającymi odpowiedziami. Wartość tego nagłówka jest równa wartości x-ms-client-request-id nagłówka, jeśli jest obecna w żądaniu, a wartość zawiera nie więcej niż 1024 widoczne znaki ASCII. x-ms-client-request-id Jeśli nagłówek nie znajduje się w żądaniu, nie będzie on obecny w odpowiedzi.

Przykładowa odpowiedź

Response Status:  
HTTP/1.1 201 Created  
  
Response Headers:  
Transfer-Encoding: chunked  
x-ms-content-crc64: 77uWZTolTHU  
Date: Sat, 31 Mar 2018 23:47:09 GMT  
Server: Windows-Azure-Blob/1.0 Microsoft-HTTPAPI/2.0

Autoryzacja

Autoryzacja jest wymagana podczas wywoływania dowolnej operacji dostępu do danych w usłudze Azure Storage. Możesz autoryzować operację Put Block From URL zgodnie z poniższym opisem.

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 autoryzację żądań do danych obiektów blob przy użyciu Tożsamość Microsoft Entra. Dzięki 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 wywołania Put Block From URL operacji 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.

Uwagi

Put Block From URL przekazuje blok do przyszłego włączenia do blokowego obiektu blob. Blokowy obiekt blob może zawierać maksymalnie 50 000 bloków. Każdy blok może mieć inny rozmiar. Maksymalny rozmiar bloku przekazanego za pomocą Put Block From URL to 100 mebibajtów (MiB). Aby przekazać większe bloki (do 4000 MIB), zobacz Put Block (Umieść blok).

W wersji 2020-10-02 lub nowszej autoryzacja Microsoft Entra jest obsługiwana dla źródła operacji kopiowania.

Obiekt blob może mieć w dowolnym momencie maksymalnie 100 000 niezatwierdzonych bloków. Jeśli ta wartość maksymalna zostanie przekroczona, usługa zwróci kod stanu 409 (RequestEntityTooLargeBlockCountExceedsLimit).

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 Put Block From URL) Maksymalny rozmiar obiektu blob (za pośrednictwem Put Block List) Maksymalny rozmiar obiektu blob za pośrednictwem operacji pojedynczego zapisu (za pośrednictwem Put Blob From URL)
Wersja 2020-04-08 lub nowsza 4000 MiB Około 190,7 tebibajtów (TiB) (4000 miB × 50 000 bloków) 5000 MiB
Wersje starsze niż 2020-04-08 100 MiB Około 4,75 TiB (100 MiB × 50 000 bloków) 256 MiB

Po przekazaniu zestawu bloków można utworzyć lub zaktualizować obiekt blob na serwerze z tego zestawu, wywołując operację Umieszczanie listy bloków . Każdy blok w zestawie jest identyfikowany przez identyfikator bloku, który jest unikatowy w ramach tego obiektu blob. Identyfikatory bloków są ograniczone do określonego obiektu blob, więc różne obiekty blob mogą mieć bloki z tymi samymi identyfikatorami.

Jeśli wywołasz Put Block From URL obiekt blob, który jeszcze nie istnieje, zostanie utworzony nowy blokowy obiekt blob o długości 0. Ten obiekt blob jest wyliczany przez operację, List Blobs jeśli zostanie określona include=uncommittedblobs opcja. Przekazany blok lub bloki nie zostaną zatwierdzone do momentu wywołania Put Block List nowego obiektu blob. Utworzony w ten sposób obiekt blob jest utrzymywany na serwerze przez tydzień. Jeśli w tym czasie nie dodano więcej bloków ani zatwierdzonych bloków do obiektu blob, obiekt blob jest zbierany w pamięci.

Blok, który został pomyślnie przekazany z operacją Put Block From URL , nie staje się częścią obiektu blob, dopóki nie zostanie zatwierdzony za pomocą Put Block Listpolecenia . Przed Put Block List wywołaniem w celu zatwierdzenia nowego lub zaktualizowanego obiektu blob wszystkie wywołania funkcji Get Blob zwracają zawartość obiektu blob bez dołączania niezatwierdzonego bloku.

Jeśli przekażesz blok o tym samym identyfikatorze bloku co inny blok, który nie został jeszcze zatwierdzony, ostatni przekazany blok o tym identyfikatorze zostanie zatwierdzony podczas następnej pomyślnej Put Block List operacji.

Po Put Block List wywołaniu wszystkie niezatwierdzone bloki określone na liście bloków są zatwierdzane w ramach nowego obiektu blob. Wszystkie niezatwierdzone bloki, które nie zostały określone na liście bloków dla obiektu blob, są zbierane i usuwane z usługi Blob Storage. Wszystkie niezatwierdzone bloki są również wyrzucane na śmieci, jeśli nie ma żadnych pomyślnych wywołań do Put Block From URL lub Put Block List na tym samym obiekcie blob w ciągu tygodnia po ostatniej pomyślnej Put Block From URL operacji. Jeśli obiekt Blob Put jest wywoływany w obiekcie blob, wszystkie niezatwierdzone bloki są zbierane w pamięci.

Jeśli obiekt blob ma aktywną dzierżawę, klient musi określić prawidłowy identyfikator dzierżawy żądania, aby zapisać blok w obiekcie blob. Jeśli klient nie określi identyfikatora dzierżawy lub określa nieprawidłowy identyfikator dzierżawy, usługa Blob Storage zwraca kod stanu 412 (Warunek wstępny nie powiodło się). Jeśli klient określa identyfikator dzierżawy, ale obiekt blob nie ma aktywnej dzierżawy, usługa Blob Storage zwraca również kod stanu 412 (Warunek wstępny nie powiodło się).

W przypadku określonego obiektu blob wszystkie identyfikatory bloków muszą mieć taką samą długość. Jeśli blok zostanie przekazany z identyfikatorem bloku o innej długości niż identyfikatory bloków dla istniejących niezatwierdzonych bloków, usługa zwraca kod odpowiedzi błędu 400 (Nieprawidłowe żądanie).

Wywołanie Put Block From URL nie aktualizuje czasu ostatniej modyfikacji istniejącego obiektu blob.

Wywołanie Put Block From URL stronicowego obiektu blob zwraca błąd.

Wywołanie Put Block From URL obiektu blob "archiwum" zwraca błąd i wywoływanie go w hot obiekcie blob cool nie zmienia warstwy obiektu blob.

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 Put Block From URL żądań na podstawie typu konta magazynu:

Operacja Typ konta magazynu Kategoria rozliczeń
Umieść blok 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
Umieść blok 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 naliczane za jedną transakcję w celu zainicjowania zapisu.
2Konto źródłowe powoduje naliczenie jednej transakcji dla każdego żądania odczytu do obiektu źródłowego.

Ponadto jeśli konta źródłowe i docelowe znajdują się w różnych regionach (na przykład Północno-wschodnie stany USA i Południowe stany USA), przepustowość używana do transferu żądania jest obciążana za źródłowe konto magazynu jako ruch wychodzący. Ruch wychodzący między kontami w tym samym regionie jest bezpłatny.

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

Zobacz też