Skip to content

Added docs and readme samples for copy blob #15560

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
rickle-msft merged 2 commits into from
Oct 2, 2020
Merged

Added docs and readme samples for copy blob #15560

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
ba11972
Added docs and readme samples for copy blob
rickle-msft Sep 22, 2020
538e8c2
fixed some embedme line numbers
rickle-msft Sep 23, 2020
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
51 changes: 35 additions & 16 deletions sdk/storage/azure-storage-blob/README.md
View file
Open in desktop
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));
Copy link
Member

@gapra-msft gapra-msft Sep 23, 2020

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Should we maybe add like if you get a CannotVerifyCopySource, make sure authentication is correct?

Copy link
Contributor Author

@rickle-msft rickle-msft Oct 2, 2020

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Spoke offline. It's atypical for us to call out specific error codes in our docs at the moment, so I'll leave this out for now. If these updates still are insufficient to help customers solve their own issues, we can add in call-outs to that error code later.

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
Open in desktop
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
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -268,6 +268,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 @@ -292,6 +297,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 @@ -324,6 +334,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 @@ -380,6 +395,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 @@ -398,6 +416,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 @@ -429,6 +450,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
Open in desktop
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");
}
}