Skip to content

Commit

Permalink
Added docs and readme samples for copy blob (Azure#15560)
Browse files Browse the repository at this point in the history 
* Added docs and readme samples for copy blob

* fixed some embedme line numbers
  • Loading branch information
@rickle-msft
rickle-msft authored Oct 2, 2020
1 parent 4843871 commit c3bdd28
Show file tree
Hide file tree
Showing 4 changed files with 95 additions and 17 deletions.
51 changes: 35 additions & 16 deletions sdk/storage/azure-storage-blob/README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -149,13 +149,14 @@ The following sections provide several code snippets covering some of the most c
- [Download a blob to a stream](#download-a-blob-to-a-stream)
- [Download a blob to local path](#download-a-blob-to-local-path)
- [Enumerate blobs](#enumerate-blobs)
- [Copy a blob](#copy-a-blob)
- [Authenticate with Azure Identity](#authenticate-with-azure-identity)

### Create a `BlobServiceClient`

Create a `BlobServiceClient` using the [`sasToken`](#get-credentials) generated above.

<!-- embedme ./src/samples/java/com/azure/storage/blob/ReadmeSamples.java#L27-L30 -->
<!-- embedme ./src/samples/java/com/azure/storage/blob/ReadmeSamples.java#L30-L33 -->
```java
BlobServiceClient blobServiceClient = new BlobServiceClientBuilder()
.endpoint("<your-storage-account-url>")
Expand All @@ -165,7 +166,7 @@ BlobServiceClient blobServiceClient = new BlobServiceClientBuilder()

or

<!-- embedme ./src/samples/java/com/azure/storage/blob/ReadmeSamples.java#L34-L37 -->
<!-- embedme ./src/samples/java/com/azure/storage/blob/ReadmeSamples.java#L37-L40 -->
```java
// Only one "?" is needed here. If the sastoken starts with "?", please removing one "?".
BlobServiceClient blobServiceClient = new BlobServiceClientBuilder()
Expand All @@ -177,14 +178,14 @@ BlobServiceClient blobServiceClient = new BlobServiceClientBuilder()

Create a `BlobContainerClient` using a `BlobServiceClient`.

<!-- embedme ./src/samples/java/com/azure/storage/blob/ReadmeSamples.java#L41-L41 -->
<!-- embedme ./src/samples/java/com/azure/storage/blob/ReadmeSamples.java#L44-L44 -->
```java
BlobContainerClient blobContainerClient = blobServiceClient.getBlobContainerClient("mycontainer");
```

Create a `BlobContainerClient` from the builder [`sasToken`](#get-credentials) generated above.

<!-- embedme ./src/samples/java/com/azure/storage/blob/ReadmeSamples.java#L45-L49 -->
<!-- embedme ./src/samples/java/com/azure/storage/blob/ReadmeSamples.java#L48-L52 -->
```java
BlobContainerClient blobContainerClient = new BlobContainerClientBuilder()
.endpoint("<your-storage-account-url>")
Expand All @@ -195,7 +196,7 @@ BlobContainerClient blobContainerClient = new BlobContainerClientBuilder()

or

<!-- embedme ./src/samples/java/com/azure/storage/blob/ReadmeSamples.java#L53-L56 -->
<!-- embedme ./src/samples/java/com/azure/storage/blob/ReadmeSamples.java#L56-L59 -->
```java
// Only one "?" is needed here. If the sastoken starts with "?", please removing one "?".
BlobContainerClient blobContainerClient = new BlobContainerClientBuilder()
Expand All @@ -207,7 +208,7 @@ BlobContainerClient blobContainerClient = new BlobContainerClientBuilder()

Create a `BlobClient` using a `BlobContainerClient`.

<!-- embedme ./src/samples/java/com/azure/storage/blob/ReadmeSamples.java#L60-L60 -->
<!-- embedme ./src/samples/java/com/azure/storage/blob/ReadmeSamples.java#L63-L63 -->
```java
BlobClient blobClient = blobContainerClient.getBlobClient("myblob");
```
Expand All @@ -216,7 +217,7 @@ or

Create a `BlobClient` from the builder [`sasToken`](#get-credentials) generated above.

<!-- embedme ./src/samples/java/com/azure/storage/blob/ReadmeSamples.java#L64-L69 -->
<!-- embedme ./src/samples/java/com/azure/storage/blob/ReadmeSamples.java#L67-L72 -->
```java
BlobClient blobClient = new BlobClientBuilder()
.endpoint("<your-storage-account-url>")
Expand All @@ -228,7 +229,7 @@ BlobClient blobClient = new BlobClientBuilder()

or

<!-- embedme ./src/samples/java/com/azure/storage/blob/ReadmeSamples.java#L73-L76 -->
<!-- embedme ./src/samples/java/com/azure/storage/blob/ReadmeSamples.java#L76-L79 -->
```java
// Only one "?" is needed here. If the sastoken starts with "?", please removing one "?".
BlobClient blobClient = new BlobClientBuilder()
Expand All @@ -240,7 +241,7 @@ BlobClient blobClient = new BlobClientBuilder()

Create a container using a `BlobServiceClient`.

<!-- embedme ./src/samples/java/com/azure/storage/blob/ReadmeSamples.java#L80-L80 -->
<!-- embedme ./src/samples/java/com/azure/storage/blob/ReadmeSamples.java#L83-L83 -->
```java
blobServiceClient.createBlobContainer("mycontainer");
```
Expand All @@ -249,7 +250,7 @@ or

Create a container using a `BlobContainerClient`.

<!-- embedme ./src/samples/java/com/azure/storage/blob/ReadmeSamples.java#L84-L84 -->
<!-- embedme ./src/samples/java/com/azure/storage/blob/ReadmeSamples.java#L87-L87 -->
```java
blobContainerClient.create();
```
Expand All @@ -258,7 +259,7 @@ blobContainerClient.create();

Upload from an `InputStream` to a blob using a `BlockBlobClient` generated from a `BlobContainerClient`.

<!-- embedme ./src/samples/java/com/azure/storage/blob/ReadmeSamples.java#L88-L94 -->
<!-- embedme ./src/samples/java/com/azure/storage/blob/ReadmeSamples.java#L91-L97 -->
```java
BlockBlobClient blockBlobClient = blobContainerClient.getBlobClient("myblockblob").getBlockBlobClient();
String dataSample = "samples";
Expand All @@ -273,7 +274,7 @@ try (ByteArrayInputStream dataStream = new ByteArrayInputStream(dataSample.getBy

Upload a file to a blob using a `BlobClient` generated from a `BlobContainerClient`.

<!-- embedme ./src/samples/java/com/azure/storage/blob/ReadmeSamples.java#L98-L99 -->
<!-- embedme ./src/samples/java/com/azure/storage/blob/ReadmeSamples.java#L101-L102 -->
```java
BlobClient blobClient = blobContainerClient.getBlobClient("myblockblob");
blobClient.uploadFromFile("local-file.jpg");
Expand All @@ -283,7 +284,7 @@ blobClient.uploadFromFile("local-file.jpg");

Download a blob to an `OutputStream` using a `BlobClient`.

<!-- embedme ./src/samples/java/com/azure/storage/blob/ReadmeSamples.java#L103-L107 -->
<!-- embedme ./src/samples/java/com/azure/storage/blob/ReadmeSamples.java#L106-L110 -->
```java
try (ByteArrayOutputStream outputStream = new ByteArrayOutputStream()) {
blobClient.download(outputStream);
Expand All @@ -296,7 +297,7 @@ try (ByteArrayOutputStream outputStream = new ByteArrayOutputStream()) {

Download blob to a local file using a `BlobClient`.

<!-- embedme ./src/samples/java/com/azure/storage/blob/ReadmeSamples.java#L111-L111 -->
<!-- embedme ./src/samples/java/com/azure/storage/blob/ReadmeSamples.java#L114-L114 -->
```java
blobClient.downloadToFile("downloaded-file.jpg");
```
Expand All @@ -305,18 +306,36 @@ blobClient.downloadToFile("downloaded-file.jpg");

Enumerating all blobs using a `BlobContainerClient`.

<!-- embedme ./src/samples/java/com/azure/storage/blob/ReadmeSamples.java#L115-L117 -->
<!-- embedme ./src/samples/java/com/azure/storage/blob/ReadmeSamples.java#L118-L120 -->
```java
for (BlobItem blobItem : blobContainerClient.listBlobs()) {
System.out.println("This is the blob name: " + blobItem.getName());
}
```

### Copy a blob

Copying a blob. Please refer to the javadocs on each of these methods for more information around requirements on the
copy source and its authentication.

<!-- embedme ./src/samples/java/com/azure/storage/blob/ReadmeSamples.java#L131-L132 -->
```java
SyncPoller<BlobCopyInfo, Void> poller = blobClient.beginCopy("<url-to-blob>", Duration.ofSeconds(1));
poller.waitForCompletion();
```

or

<!-- embedme ./src/samples/java/com/azure/storage/blob/ReadmeSamples.java#L136-L136 -->
```java
blobClient.copyFromUrl("url-to-blob");
```

### Authenticate with Azure Identity

The [Azure Identity library][identity] provides Azure Active Directory support for authenticating with Azure Storage.

<!-- embedme ./src/samples/java/com/azure/storage/blob/ReadmeSamples.java#L121-L124 -->
<!-- embedme ./src/samples/java/com/azure/storage/blob/ReadmeSamples.java#L124-L127 -->
```java
BlobServiceClient blobStorageClient = new BlobServiceClientBuilder()
.endpoint("<your-storage-account-url>")
Expand Down
26 changes: 25 additions & 1 deletion ...re-storage-blob/src/main/java/com/azure/storage/blob/specialized/BlobAsyncClientBase.java
View file
Original file line number Diff line number Diff line change
Expand Up @@ -397,6 +397,11 @@ Mono<Response<Boolean>> existsWithResponse(Context context) {

/**
* Copies the data at the source URL to a blob.
* <p>
* This method triggers a long-running, asynchronous operations. The source may be another blob or an Azure File. If
* the source is in another account, the source must either be public or authenticated with a SAS token. If the
* source is in the same account, the Shared Key authorization on the destination will also be applied to the
* source. The source URL must be URL encoded.
*
* <p><strong>Code Samples</strong></p>
*
Expand All @@ -417,6 +422,11 @@ public PollerFlux<BlobCopyInfo, Void> beginCopy(String sourceUrl, Duration pollI

/**
* Copies the data at the source URL to a blob.
* <p>
* This method triggers a long-running, asynchronous operations. The source may be another blob or an Azure File. If
* the source is in another account, the source must either be public or authenticated with a SAS token. If the
* source is in the same account, the Shared Key authorization on the destination will also be applied to the
* source. The source URL must be URL encoded.
*
* <p><strong>Starting a copy operation</strong></p>
* Starting a copy operation and polling on the responses.
Expand Down Expand Up @@ -451,6 +461,11 @@ public PollerFlux<BlobCopyInfo, Void> beginCopy(String sourceUrl, Map<String, St

/**
* Copies the data at the source URL to a blob.
* <p>
* This method triggers a long-running, asynchronous operations. The source may be another blob or an Azure File. If
* the source is in another account, the source must either be public or authenticated with a SAS token. If the
* source is in the same account, the Shared Key authorization on the destination will also be applied to the
* source. The source URL must be URL encoded.
*
* <p><strong>Starting a copy operation</strong></p>
* Starting a copy operation and polling on the responses.
Expand Down Expand Up @@ -664,6 +679,9 @@ Mono<Response<Void>> abortCopyFromUrlWithResponse(String copyId, String leaseId,

/**
* Copies the data at the source URL to a blob and waits for the copy to complete before returning a response.
* <p>
* The source must be a block blob no larger than 256MB. The source must also be either public or have a sas token
* attached. The URL must be URL encoded.
*
* <p><strong>Code Samples</strong></p>
*
Expand All @@ -685,6 +703,9 @@ public Mono<String> copyFromUrl(String copySource) {

/**
* Copies the data at the source URL to a blob and waits for the copy to complete before returning a response.
* <p>
* The source must be a block blob no larger than 256MB. The source must also be either public or have a sas token
* attached. The URL must be URL encoded.
*
* <p><strong>Code Samples</strong></p>
*
Expand Down Expand Up @@ -713,7 +734,10 @@ public Mono<Response<String>> copyFromUrlWithResponse(String copySource, Map<Str

/**
* Copies the data at the source URL to a blob and waits for the copy to complete before returning a response.
*
* <p>
* The source must be a block blob no larger than 256MB. The source must also be either public or have a sas token
* attached. The URL must be URL encoded.
*
* <p><strong>Code Samples</strong></p>
*
* {@codesnippet com.azure.storage.blob.specialized.BlobAsyncClientBase.copyFromUrlWithResponse#BlobCopyFromUrlOptions}
Expand Down
24 changes: 24 additions & 0 deletions ...e/azure-storage-blob/src/main/java/com/azure/storage/blob/specialized/BlobClientBase.java
View file
Original file line number Diff line number Diff line change
Expand Up @@ -286,6 +286,11 @@ public Response<Boolean> existsWithResponse(Duration timeout, Context context) {

/**
* Copies the data at the source URL to a blob.
* <p>
* This method triggers a long-running, asynchronous operations. The source may be another blob or an Azure File. If
* the source is in another account, the source must either be public or authenticated with a SAS token. If the
* source is in the same account, the Shared Key authorization on the destination will also be applied to the
* source. The source URL must be URL encoded.
*
* <p><strong>Code Samples</strong></p>
*
Expand All @@ -310,6 +315,11 @@ public SyncPoller<BlobCopyInfo, Void> beginCopy(String sourceUrl, Duration pollI

/**
* Copies the data at the source URL to a blob.
* <p>
* This method triggers a long-running, asynchronous operations. The source may be another blob or an Azure File. If
* the source is in another account, the source must either be public or authenticated with a SAS token. If the
* source is in the same account, the Shared Key authorization on the destination will also be applied to the
* source. The source URL must be URL encoded.
*
* <p><strong>Code Samples</strong></p>
*
Expand Down Expand Up @@ -342,6 +352,11 @@ public SyncPoller<BlobCopyInfo, Void> beginCopy(String sourceUrl, Map<String, St

/**
* Copies the data at the source URL to a blob.
* <p>
* This method triggers a long-running, asynchronous operations. The source may be another blob or an Azure File. If
* the source is in another account, the source must either be public or authenticated with a SAS token. If the
* source is in the same account, the Shared Key authorization on the destination will also be applied to the
* source. The source URL must be URL encoded.
*
* <p><strong>Code Samples</strong></p>
*
Expand Down Expand Up @@ -398,6 +413,9 @@ public Response<Void> abortCopyFromUrlWithResponse(String copyId, String leaseId

/**
* Copies the data at the source URL to a blob and waits for the copy to complete before returning a response.
* <p>
* The source must be a block blob no larger than 256MB. The source must also be either public or have a sas token
* attached. The URL must be URL encoded.
*
* <p><strong>Code Samples</strong></p>
*
Expand All @@ -416,6 +434,9 @@ public String copyFromUrl(String copySource) {

/**
* Copies the data at the source URL to a blob and waits for the copy to complete before returning a response.
* <p>
* The source must be a block blob no larger than 256MB. The source must also be either public or have a sas token
* attached. The URL must be URL encoded.
*
* <p><strong>Code Samples</strong></p>
*
Expand Down Expand Up @@ -447,6 +468,9 @@ public Response<String> copyFromUrlWithResponse(String copySource, Map<String, S

/**
* Copies the data at the source URL to a blob and waits for the copy to complete before returning a response.
* <p>
* The source must be a block blob no larger than 256MB. The source must also be either public or have a sas token
* attached. The URL must be URL encoded.
*
* <p><strong>Code Samples</strong></p>
*
Expand Down
11 changes: 11 additions & 0 deletions sdk/storage/azure-storage-blob/src/samples/java/com/azure/storage/blob/ReadmeSamples.java
View file
Original file line number Diff line number Diff line change
Expand Up @@ -2,13 +2,16 @@
// Licensed under the MIT License.
package com.azure.storage.blob;

import com.azure.core.util.polling.SyncPoller;
import com.azure.identity.DefaultAzureCredentialBuilder;
import com.azure.storage.blob.models.BlobCopyInfo;
import com.azure.storage.blob.models.BlobItem;
import com.azure.storage.blob.specialized.BlockBlobClient;

import java.io.ByteArrayInputStream;
import java.io.ByteArrayOutputStream;
import java.io.IOException;
import java.time.Duration;

/**
* WARNING: MODIFYING THIS FILE WILL REQUIRE CORRESPONDING UPDATES TO README.md FILE. LINE NUMBERS
Expand Down Expand Up @@ -124,5 +127,13 @@ public void authWithIdentity() {
.buildClient();
}

public void copyBlob() {
SyncPoller<BlobCopyInfo, Void> poller = blobClient.beginCopy("<url-to-blob>", Duration.ofSeconds(1));
poller.waitForCompletion();
}

public void copyBlob2() {
blobClient.copyFromUrl("url-to-blob");
}
}

0 comments on commit c3bdd28

Please sign in to comment.