-
Notifications
You must be signed in to change notification settings - Fork 836
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
azfile: Adding readme and changelog (#20714)
* Adding README * Adding doc.go * Adding log.go * Adding changelog
- Loading branch information
1 parent
e6caef7
commit 1a3504e
Showing
16 changed files
with
603 additions
and
54 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,266 @@ | ||
# Azure File Storage SDK for Go | ||
|
||
> Service Version: 2020-10-02 | ||
Azure File Shares offers fully managed file shares in the cloud that are accessible via the industry standard | ||
[Server Message Block (SMB) protocol](https://docs.microsoft.com/windows/desktop/FileIO/microsoft-smb-protocol-and-cifs-protocol-overview). | ||
Azure file shares can be mounted concurrently by cloud or on-premises deployments of Windows, Linux, and macOS. | ||
Additionally, Azure file shares can be cached on Windows Servers with Azure File Sync for fast access near where the data is being used. | ||
|
||
[Source code][source] | [API reference documentation][docs] | [REST API documentation][rest_docs] | [Product documentation][product_docs] | ||
|
||
## Getting started | ||
|
||
### Install the package | ||
|
||
Install the Azure File Storage SDK for Go with [go get][goget]: | ||
|
||
```Powershell | ||
go get github.com/Azure/azure-sdk-for-go/sdk/storage/azfile | ||
``` | ||
|
||
### Prerequisites | ||
|
||
A supported [Go][godevdl] version (the Azure SDK supports the two most recent Go releases). | ||
|
||
You need an [Azure subscription][azure_sub] and a | ||
[Storage Account][storage_account_docs] to use this package. | ||
|
||
To create a new Storage Account, you can use the [Azure Portal][storage_account_create_portal], | ||
[Azure PowerShell][storage_account_create_ps], or the [Azure CLI][storage_account_create_cli]. | ||
Here's an example using the Azure CLI: | ||
|
||
```Powershell | ||
az storage account create --name MyStorageAccount --resource-group MyResourceGroup --location westus --sku Standard_LRS | ||
``` | ||
|
||
### Authenticate the client | ||
|
||
The Azure File Storage SDK for Go allows you to interact with four types of resources: the storage | ||
account itself, file shares, directories, and files. Interaction with these resources starts with an instance of a | ||
client. To create a client object, you will need the storage account's file service URL and a | ||
credential that allows you to access the storage account: | ||
|
||
```go | ||
// create a credential for authenticating using shared key | ||
cred, err := service.NewSharedKeyCredential("<my-storage-account-name>", "<my-storage-account-key>") | ||
// TODO: handle err | ||
|
||
// create service.Client for the specified storage account that uses the above credential | ||
client, err := service.NewClientWithSharedKeyCredential("https://<my-storage-account-name>.file.core.windows.net/", cred, nil) | ||
// TODO: handle err | ||
``` | ||
|
||
## Key concepts | ||
|
||
Azure file shares can be used to: | ||
|
||
- Completely replace or supplement traditional on-premises file servers or NAS devices. | ||
- "Lift and shift" applications to the cloud that expect a file share to store file application or user data. | ||
- Simplify new cloud development projects with shared application settings, diagnostic shares, and Dev/Test/Debug tool file shares. | ||
|
||
### Goroutine safety | ||
We guarantee that all client instance methods are goroutine-safe and independent of each other ([guideline](https://azure.github.io/azure-sdk/golang_introduction.html#thread-safety)). This ensures that the recommendation of reusing client instances is always safe, even across goroutines. | ||
|
||
### Additional concepts | ||
<!-- CLIENT COMMON BAR --> | ||
[Client options](https://pkg.go.dev/github.com/Azure/azure-sdk-for-go/sdk/azcore/policy#ClientOptions) | | ||
[Accessing the response](https://pkg.go.dev/github.com/Azure/azure-sdk-for-go/sdk/azcore/runtime#WithCaptureResponse) | | ||
[Handling failures](https://pkg.go.dev/github.com/Azure/azure-sdk-for-go/sdk/azcore#ResponseError) | | ||
[Logging](https://pkg.go.dev/github.com/Azure/azure-sdk-for-go/sdk/azcore/log) | ||
<!-- CLIENT COMMON BAR --> | ||
|
||
## Examples | ||
|
||
### Create a share and upload a file | ||
|
||
```go | ||
const ( | ||
shareName = "sample-share" | ||
dirName = "sample-dir" | ||
fileName = "sample-file" | ||
) | ||
|
||
// Get a connection string to our Azure Storage account. You can | ||
// obtain your connection string from the Azure Portal (click | ||
// Access Keys under Settings in the Portal Storage account blade) | ||
// or using the Azure CLI with: | ||
// | ||
// az storage account show-connection-string --name <account_name> --resource-group <resource_group> | ||
// | ||
// And you can provide the connection string to your application | ||
// using an environment variable. | ||
connectionString := "<connection_string>" | ||
|
||
// Path to the local file to upload | ||
localFilePath := "<path_to_local_file>" | ||
|
||
// Get reference to a share and create it | ||
shareClient, err := share.NewClientFromConnectionString(connectionString, shareName, nil) | ||
// TODO: handle error | ||
_, err = shareClient.Create(context.TODO(), nil) | ||
// TODO: handle error | ||
|
||
// Get reference to a directory and create it | ||
dirClient := shareClient.NewDirectoryClient(dirName) | ||
_, err = dirClient.Create(context.TODO(), nil) | ||
// TODO: handle error | ||
|
||
// open the file for reading | ||
file, err := os.OpenFile(localFilePath, os.O_RDONLY, 0) | ||
// TODO: handle error | ||
defer file.Close() | ||
|
||
// get the size of file | ||
fInfo, err := file.Stat() | ||
// TODO: handle error | ||
fSize := fInfo.Size() | ||
|
||
// create the file | ||
fClient := dirClient.NewFileClient(fileName) | ||
_, err = fClient.Create(context.TODO(), fSize, nil) | ||
// TODO: handle error | ||
|
||
// upload the file | ||
err = fClient.UploadFile(context.TODO(), file, nil) | ||
// TODO: handle error | ||
``` | ||
|
||
### Download a file | ||
|
||
```go | ||
const ( | ||
shareName = "sample-share" | ||
dirName = "sample-dir" | ||
fileName = "sample-file" | ||
) | ||
|
||
connectionString := "<connection_string>" | ||
|
||
// Path to the save the downloaded file | ||
localFilePath := "<path_to_local_file>" | ||
|
||
// Get reference to the share | ||
shareClient, err := share.NewClientFromConnectionString(connectionString, shareName, nil) | ||
// TODO: handle error | ||
|
||
// Get reference to the directory | ||
dirClient := shareClient.NewDirectoryClient(dirName) | ||
|
||
// Get reference to the file | ||
fClient := dirClient.NewFileClient(fileName) | ||
|
||
// create or open a local file where we can download the Azure File | ||
file, err := os.Create(localFilePath) | ||
// TODO: handle error | ||
defer file.Close() | ||
|
||
// Download the file | ||
_, err = fClient.DownloadFile(context.TODO(), file, nil) | ||
// TODO: handle error | ||
``` | ||
|
||
### Traverse a share | ||
|
||
```go | ||
const shareName = "sample-share" | ||
|
||
connectionString := "<connection_string>" | ||
|
||
// Get reference to the share | ||
shareClient, err := share.NewClientFromConnectionString(connectionString, shareName, nil) | ||
// TODO: handle error | ||
|
||
// Track the remaining directories to walk, starting from the root | ||
var dirs []*directory.Client | ||
dirs = append(dirs, shareClient.NewRootDirectoryClient()) | ||
for len(dirs) > 0 { | ||
dirClient := dirs[0] | ||
dirs = dirs[1:] | ||
|
||
// Get all the next directory's files and subdirectories | ||
pager := dirClient.NewListFilesAndDirectoriesPager(nil) | ||
for pager.More() { | ||
resp, err := pager.NextPage(context.TODO()) | ||
// TODO: handle error | ||
|
||
for _, d := range resp.Segment.Directories { | ||
fmt.Println(*d.Name) | ||
// Keep walking down directories | ||
dirs = append(dirs, dirClient.NewSubdirectoryClient(*d.Name)) | ||
} | ||
|
||
for _, f := range resp.Segment.Files { | ||
fmt.Println(*f.Name) | ||
} | ||
} | ||
} | ||
``` | ||
|
||
## Troubleshooting | ||
|
||
All File service operations will return an | ||
[*azcore.ResponseError][azcore_response_error] on failure with a | ||
populated `ErrorCode` field. Many of these errors are recoverable. | ||
The [fileerror][file_error] package provides the possible Storage error codes | ||
along with various helper facilities for error handling. | ||
|
||
```go | ||
const ( | ||
connectionString = "<connection_string>" | ||
shareName = "sample-share" | ||
) | ||
|
||
// create a client with the provided connection string | ||
client, err := service.NewClientFromConnectionString(connectionString, nil) | ||
// TODO: handle error | ||
|
||
// try to delete the share, avoiding any potential race conditions with an in-progress or completed deletion | ||
_, err = client.DeleteShare(context.TODO(), shareName, nil) | ||
|
||
if fileerror.HasCode(err, fileerror.ShareBeingDeleted, fileerror.ShareNotFound) { | ||
// ignore any errors if the share is being deleted or already has been deleted | ||
} else if err != nil { | ||
// TODO: some other error | ||
} | ||
``` | ||
|
||
## Next steps | ||
|
||
Get started with our [File samples][samples]. They contain complete examples of the above snippets and more. | ||
|
||
## Contributing | ||
|
||
See the [Storage CONTRIBUTING.md][storage_contrib] for details on building, | ||
testing, and contributing to this library. | ||
|
||
This project welcomes contributions and suggestions. Most contributions require | ||
you to agree to a Contributor License Agreement (CLA) declaring that you have | ||
the right to, and actually do, grant us the rights to use your contribution. For | ||
details, visit [cla.microsoft.com][cla]. | ||
|
||
This project has adopted the [Microsoft Open Source Code of Conduct][coc]. | ||
For more information see the [Code of Conduct FAQ][coc_faq] | ||
or contact [opencode@microsoft.com][coc_contact] with any | ||
additional questions or comments. | ||
|
||
<!-- LINKS --> | ||
[source]: https://github.com/Azure/azure-sdk-for-go/tree/main/sdk/storage | ||
[docs]: https://pkg.go.dev/github.com/Azure/azure-sdk-for-go/sdk/storage/azfile | ||
[rest_docs]: https://docs.microsoft.com/rest/api/storageservices/file-service-rest-api | ||
[product_docs]: https://docs.microsoft.com/azure/storage/files/storage-files-introduction | ||
[godevdl]: https://go.dev/dl/ | ||
[goget]: https://pkg.go.dev/cmd/go#hdr-Add_dependencies_to_current_module_and_install_them | ||
[storage_account_docs]: https://docs.microsoft.com/azure/storage/common/storage-account-overview | ||
[storage_account_create_ps]: https://docs.microsoft.com/azure/storage/common/storage-quickstart-create-account?tabs=azure-powershell | ||
[storage_account_create_cli]: https://docs.microsoft.com/azure/storage/common/storage-quickstart-create-account?tabs=azure-cli | ||
[storage_account_create_portal]: https://docs.microsoft.com/azure/storage/common/storage-quickstart-create-account?tabs=azure-portal | ||
[azure_sub]: https://azure.microsoft.com/free/ | ||
[azcore_response_error]: https://pkg.go.dev/github.com/Azure/azure-sdk-for-go/sdk/azcore#ResponseError | ||
[file_error]: https://github.com/Azure/azure-sdk-for-go/tree/main/sdk/storage | ||
[samples]: https://github.com/Azure/azure-sdk-for-go/blob/main/sdk/storage | ||
[storage_contrib]: https://github.com/Azure/azure-sdk-for-go/blob/main/CONTRIBUTING.md | ||
[cla]: https://cla.microsoft.com | ||
[coc]: https://opensource.microsoft.com/codeofconduct/ | ||
[coc_faq]: https://opensource.microsoft.com/codeofconduct/faq/ | ||
[coc_contact]: mailto:opencode@microsoft.com |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Oops, something went wrong.