Merge pull request #213497 from normesta/azcopy

Updating guidelines for better visibility

Author: jborsecnik

articles/storage/common/storage-ref-azcopy-copy.md

@@ -4,15 +4,16 @@ description: This article provides reference information for the azcopy copy com
 author: normesta
 ms.service: storage
 ms.topic: reference
-ms.date: 05/26/2022
+ms.date: 10/22/2022
 ms.author: normesta
 ms.subservice: common
 ms.reviewer: zezha-msft
 ---
 
 # azcopy copy
 
-Copies source data to a destination location.
+Copies source data to a destination location.  
+
 
 ## Synopsis
 
@@ -48,6 +49,12 @@ If you set an environment variable by using the command line, that variable will
 azcopy copy [source] [destination] [flags]
 ```
 
+## Related conceptual articles
+
+- [Get started with AzCopy](storage-use-azcopy-v10.md)
+- [Transfer data with AzCopy and Blob storage](./storage-use-azcopy-v10.md#transfer-data)
+- [Transfer data with AzCopy and file storage](storage-use-azcopy-files.md)
+
 ## Examples
 
 Upload a single file by using OAuth authentication. If you haven't yet logged into AzCopy, please run the azcopy login command before you run the following command.
@@ -237,7 +244,7 @@ Copy a subset of buckets by using a wildcard symbol (*) in the bucket name from
 
 `--content-type`   (string)    Specifies the content type of the file. Implies no-guess-mime-type. Returned on download.
 
-`--cpk-by-name`    (string)    Client provided key by name that lets clients making requests against Azure Blob storage an option to provide an encryption key on a per-request basis. Provided key name will be fetched from Azure Key Vault and will be used to encrypt the data
+`--cpk-by-name`    (string)    Client provided key by name that gives clients making requests against Azure Blob storage an option to provide an encryption key on a per-request basis. Provided key name will be fetched from Azure Key Vault and will be used to encrypt the data
 
 `--cpk-by-value`    Client provided key by name that let clients making requests against Azure Blob storage an option to provide an encryption key on a per-request basis. Provided key and its hash will be fetched from environment variables
 

articles/storage/common/storage-ref-azcopy-sync.md

@@ -29,7 +29,13 @@ The sync command differs from the copy command in several ways:
   2. When syncing between virtual directories, add a trailing slash to the path (refer to examples) if there's a blob with the same name as one of the virtual directories.
   3. If the 'delete-destination' flag is set to true or prompt, then sync will delete files and blobs at the destination that aren't present at the source.
 
-Advanced:
+## Guidelines
+
+[!INCLUDE [Azcopy sync command general guidelines](../../../includes/azure-storage-azcopy-sync-guidelines.md)]
+
+- For Blob Storage, you can prevent accidental deletions by making sure to enable the [soft delete](../blobs/soft-delete-blob-overview.md) feature before you use the `--delete-destination=prompt|true` flag.
+
+## Advanced
 
 Note that if you don't specify a file extension, AzCopy automatically detects the content type of the files when uploading from the local disk, based on the file extension or content.
 
@@ -48,6 +54,12 @@ the header field Last-Modified is used instead of x-ms-file-change-time, which m
 azcopy sync [flags]
 ```
 
+## Related conceptual articles
+
+- [Get started with AzCopy](storage-use-azcopy-v10.md)
+- [Transfer data with AzCopy and Blob storage](./storage-use-azcopy-v10.md#transfer-data)
+- [Transfer data with AzCopy and file storage](storage-use-azcopy-files.md)
+
 ## Examples
 
 Sync a single file:

articles/storage/common/storage-use-azcopy-blobs-synchronize.md

@@ -4,7 +4,7 @@ description: This article contains a collection of AzCopy example commands that
 author: normesta
 ms.service: storage
 ms.topic: how-to
-ms.date: 04/02/2021
+ms.date: 10/02/2022
 ms.author: normesta
 ms.subservice: common
 ms.reviewer: dineshm
@@ -32,17 +32,10 @@ See the [Get started with AzCopy](storage-use-azcopy-v10.md) article to download
 
 ## Guidelines
 
-- The [sync](storage-ref-azcopy-sync.md) command compares file names and last modified timestamps. Set the `--delete-destination` optional flag to a value of `true` or `prompt` to delete files in the destination directory if those files no longer exist in the source directory.
-
-- If you set the `--delete-destination` flag to `true`, AzCopy deletes files without providing a prompt. If you want a prompt to appear before AzCopy deletes a file, set the `--delete-destination` flag to `prompt`.
-
-- If you plan to set the `--delete-destination` flag to `prompt` or `false`, consider using the [copy](storage-ref-azcopy-copy.md) command instead of the 
-[sync](storage-ref-azcopy-sync.md) command and set the `--overwrite` parameter to `ifSourceNewer`. The [copy](storage-ref-azcopy-copy.md) command consumes less memory and incurs less billing costs because a copy operation doesn't have to index the source or destination prior to moving files.
+[!INCLUDE [Azcopy sync command general guidelines](../../../includes/azure-storage-azcopy-sync-guidelines.md)]
 
 - To prevent accidental deletions, make sure to enable the [soft delete](../blobs/soft-delete-blob-overview.md) feature before you use the `--delete-destination=prompt|true` flag.
 
-- The machine on which you run the sync command should have an accurate system clock because the last modified times are critical in determining whether a file should be transferred. If your system has significant clock skew, avoid modifying files at the destination too close to the time that you plan to run a sync command.
-
 ## Update a container with changes to a local file system
 
 In this case, the container is the destination, and the local file system is the source.
@@ -79,7 +72,7 @@ azcopy sync 'https://mystorageaccount.blob.core.windows.net/mycontainer' 'C:\myD
 
 ## Update a container with changes in another container
 
-The first container that appears in this command is the source. The second one is the destination. Make sure to append a a SAS token to each source URL.
+The first container that appears in this command is the source. The second one is the destination. Make sure to append a SAS token to each source URL.
 
 If you provide authorization credentials by using Azure Active Directory (Azure AD), you can omit the SAS token only from the destination URL. Make sure that you've set up the proper roles in your destination account. See [Option 1: Use Azure Active Directory](storage-use-azcopy-v10.md?toc=/azure/storage/blobs/toc.json#option-1-use-azure-active-directory).
 
@@ -98,7 +91,7 @@ azcopy sync 'https://mysourceaccount.blob.core.windows.net/mycontainer?sv=2018-0
 
 ## Update a directory with changes to a directory in another container
 
-The first directory that appears in this command is the source. The second one is the destination. Make sure to append a a SAS token to each source URL.
+The first directory that appears in this command is the source. The second one is the destination. Make sure to append a SAS token to each source URL.
 
 If you provide authorization credentials by using Azure Active Directory (Azure AD), you can omit the SAS token only from the destination URL. Make sure that you've set up the proper roles in your destination account. See [Option 1: Use Azure Active Directory](storage-use-azcopy-v10.md?toc=/azure/storage/blobs/toc.json#option-1-use-azure-active-directory).
 

articles/storage/common/storage-use-azcopy-files.md

@@ -4,7 +4,7 @@ description: Transfer data with AzCopy and file storage. AzCopy is a command-lin
 author: normesta
 ms.service: storage
 ms.topic: how-to
-ms.date: 09/29/2022
+ms.date: 10/02/2022
 ms.author: normesta
 ms.subservice: common
 ---
@@ -425,14 +425,7 @@ You can synchronize the contents of a local file system with a file share or syn
 
 ### Guidelines
 
-- The [sync](storage-ref-azcopy-sync.md) command compares file names and last modified timestamps. Set the `--delete-destination` optional flag to a value of `true` or `prompt` to delete files in the destination directory if those files no longer exist in the source directory.
-
-- If you set the `--delete-destination` flag to `true`, AzCopy deletes files without providing a prompt. If you want a prompt to appear before AzCopy deletes a file, set the `--delete-destination` flag to `prompt`.
-
-- If you plan to set the `--delete-destination` flag to `prompt` or `false`, consider using the [copy](storage-ref-azcopy-copy.md) command instead of the 
-[sync](storage-ref-azcopy-sync.md) command and set the `--overwrite` parameter to `ifSourceNewer`. The [copy](storage-ref-azcopy-copy.md) command consumes less memory and incurs less billing costs because a copy operation doesn't have to index the source or destination prior to moving files.
-
-- The machine on which you run the sync command should have an accurate system clock because the last modified times are critical in determining whether a file should be transferred. If your system has significant clock skew, avoid modifying files at the destination too close to the time that you plan to run a sync command.
+[!INCLUDE [Azcopy sync command general guidelines](../../../includes/azure-storage-azcopy-sync-guidelines.md)]
 
 > [!TIP]
 > You can tweak your sync operation by using optional flags. Here's a few examples.

includes/azure-storage-azcopy-sync-guidelines.md

@@ -0,0 +1,18 @@
+---
+ author: normesta
+ ms.service: storage
+ ms.topic: include
+ ms.date: 10/03/2022
+ ms.author: normesta
+---
+
+ The [sync](../articles/storage/common/storage-ref-azcopy-sync.md) command compares file names and last modified timestamps. Set the `--delete-destination` optional flag to a value of `true` or `prompt` to delete files in the destination directory if those files no longer exist in the source directory.
+
+- If you set the `--delete-destination` flag to `true`, AzCopy deletes files without providing a prompt. If you want a prompt to appear before AzCopy deletes a file, set the `--delete-destination` flag to `prompt`.
+
+- If you plan to set the `--delete-destination` flag to `prompt` or `false`, consider using the [copy](../articles/storage/common/storage-ref-azcopy-copy.md) command instead of the 
+[sync](../articles/storage/common/storage-ref-azcopy-sync.md) command and set the `--overwrite` parameter to `ifSourceNewer`. The [copy](../articles/storage/common/storage-ref-azcopy-copy.md) command consumes less memory and incurs less billing costs because a copy operation doesn't have to index the source or destination prior to moving files.
+
+- The machine on which you run the sync command should have an accurate system clock because the last modified times are critical in determining whether a file should be transferred. If your system has significant clock skew, avoid modifying files at the destination too close to the time that you plan to run a sync command.
+
+- AzCopy uses server-to-server APIs to synchronize data between storage accounts. That means that data is copied directly between storage servers. However, AzCopy does set up and monitor each transfer, and for larger storage accounts (For example, accounts that contain millions of blobs), AzCopy might require a substantial amount of compute resources to accomplish these tasks. Therefore, if you are running AzCopy from Virtual Machine (VM), make sure that the VM has enough cores/memory to handle the load.