README

此项目提供了一套PHP客户端库，可以轻松访问Microsoft Azure存储服务（Blobs、Tables、Queues和Files）。有关如何在Microsoft Azure上托管PHP应用的文档，请参阅Microsoft Azure PHP开发者中心。

azure-storage-blob
azure-storage-table
azure-storage-queue
azure-storage-file
azure-storage-common

注意

如果您正在寻找服务总线、服务运行时、服务管理或媒体服务的库，请访问https://github.com/Azure/azure-sdk-for-php。

如果您需要大文件（大于2GB）或64位整数支持，请安装PHP 7 64位版本。

功能

Blobs
- 创建、列出和删除容器，处理容器元数据和权限，列出容器中的Blob
- 创建块Blob和页Blob（从流或字符串），处理Blob块和页，删除Blob
- 处理Blob属性、元数据、租约，快照Blob
Tables
- 创建和删除表
- 创建、查询、插入、更新、合并和删除实体
- 批处理操作
Queues
- 创建、列出和删除队列，处理队列元数据和属性
- 创建、获取、预览、更新和删除消息
Files
- 创建、列出和删除文件共享和目录
- 创建、删除和下载文件

请查看API参考文档中的详细信息。

入门

最低要求

PHP 5.6或更高版本
查看composer.json以获取依赖项
PHP所需扩展
- php_fileinfo.dll
- php_mbstring.dll
- php_openssl.dll
- php_xsl.dll
PHP推荐扩展
- php_curl.dll

下载源代码

要从GitHub获取源代码，请输入

git clone https://github.com/Azure/azure-storage-php.git
cd ./azure-storage-php

通过Composer安装

在项目根目录创建一个名为 composer.json 的文件，并将以下代码添加到其中

{
  "require": {
    "microsoft/azure-storage-blob": "*",
    "microsoft/azure-storage-table": "*",
    "microsoft/azure-storage-queue": "*",
    "microsoft/azure-storage-file": "*"
  }
}

在项目根目录中下载 composer.phar
打开命令提示符，并在项目根目录中执行以下操作

php composer.phar install

用法

在使用库进行调用之前，必须执行以下四个基本步骤。

首先，包含自动加载脚本

require_once "vendor/autoload.php";

包含您将要使用的命名空间。

要创建任何Microsoft Azure服务客户端，您需要使用REST代理类，例如 BlobRestProxy 类

use MicrosoftAzure\Storage\Blob\BlobRestProxy;

要处理异常，您需要

use MicrosoftAzure\Storage\Common\ServiceException;

要实例化服务客户端，您还需要一个有效的连接字符串。格式如下

DefaultEndpointsProtocol=[http|https];AccountName=[yourAccount];AccountKey=[yourKey]

或

BlobEndpoint=myBlobEndpoint;QueueEndpoint=myQueueEndpoint;TableEndpoint=myTableEndpoint;FileEndpoint=myFileEndpoint;SharedAccessSignature=sasToken

或如果使用AAD身份验证

BlobEndpoint=myBlobEndpoint;QueueEndpoint=myQueueEndpoint;TableEndpoint=myTableEndpoint;FileEndpoint=myFileEndpoint;AccountName=[yourAccount]

请注意，需要账户名称。

实例化客户端对象 - 一个包装给定服务的可用调用的包装器。

$blobClient = BlobRestProxy::createBlobService($connectionString);
$tableClient = TableRestProxy::createTableService($connectionString);
$queueClient = QueueRestProxy::createQueueService($connectionString);
$fileClient = FileRestProxy::createFileService($connectionString);

或对于AAD身份验证

$blobClient = BlobRestProxy::createBlobServiceWithTokenCredential($token, $connectionString);
$queueClient = QueueRestProxy::createQueueServiceWithTokenCredential($token, $connectionString);

请注意，Blob和Queue服务支持AAD身份验证。

使用中间件

要指定中间件，用户必须创建一个包含中间件的数组，并将其放入具有键 'middlewares' 的 $requestOptions 中。数组的顺序将影响中间件调用的顺序。通常可以在API调用的选项中设置 $requestOptions，例如 MicrosoftAzure\Storage\Blob\Models\ListBlobOptions。

如果中间件要应用于rest代理的每个API调用，则可以在创建服务时将中间件推送到具有键 'middlewares' 的服务 $_options 中。这些中间件将始终在 $requestOptions 中的中间件之后调用。例如。

$tableClient = TableRestProxy::createTableService(
    $connectionString,
    $optionsWithMiddlewares
);

每个中间件应该是实现 MicrosoftAzure\Storage\Common\Internal\IMiddleware 的子类的实例，或者是一个遵循Guzzle中间件实现约定的 callable。

用户可以创建继承自 MicrosoftAzure\Storage\Common\Internal\Middlewares\MiddlewareBase 的自定义中间件。

重试失败

您可以使用捆绑的中间件在请求失败时重试请求。首先创建中间件

$retryMiddleware = RetryMiddlewareFactory::create(
    RetryMiddlewareFactory::GENERAL_RETRY_TYPE,  // Specifies the retry logic
    3,  // Number of retries
    1000,  // Interval
    RetryMiddlewareFactory::EXPONENTIAL_INTERVAL_ACCUMULATION,  // How to increase the wait interval
    true  // Whether to retry connection failures too, default false
);

然后，如上所述在创建服务时添加中间件

$optionsWithMiddlewares = [
    'middlewares' = [
        $retryMiddleware
    ],
];
$tableClient = TableRestProxy::createTableService(
    $connectionString,
    $optionsWithMiddlewares
);

或通过将其推送到现有服务

$tableClient->pushMiddleware($retryMiddleware);

当前重试中间件不会重试以下错误

身份验证失败。
"资源未找到" 错误。
没有HTTP响应的Guzzle请求异常，例如打开流失败，或cURL连接由对方重置等。 注意： 欢迎社区贡献以覆盖Guzzle请求异常。

重试类型

RetryMiddlewareFactory::GENERAL_RETRY_TYPE - 处理重试的一般逻辑类型
RetryMiddlewareFactory::APPEND_BLOB_RETRY_TYPE - 仅用于追加blob重试，目前与通用类型相同

间隔累积

RetryMiddlewareFactory::LINEAR_INTERVAL_ACCUMULATION - 间隔将线性增加，第 n 次重试的等待时间等于 n * interval
RetryMiddlewareFactory::EXPONENTIAL_INTERVAL_ACCUMULATION - 间隔将指数增加，第 n 次重试的等待时间等于 pow(2, n) * interval

使用代理

要在HTTP请求期间使用代理，设置系统变量 HTTP_PROXY 并使用该代理。

故障排除

错误：无法获取本地颁发者证书

当尝试向Azure存储服务发出请求调用时，cURL无法验证Microsoft证书的有效性。您必须按照以下步骤配置cURL在发出https请求时使用证书：

从cURL网站下载 cacert.pem 文件。

然后：

打开您的php.ini文件并添加以下行
```
curl.cainfo = "<absolute path to cacert.pem>"
```
或者

在创建相关代理时，将 cacert 指定到选项中。

//example of creating the FileRestProxy
$options["http"] = ["verify" => "<absolute path to cacert.pem>"];
FileRestProxy::createFileService($connectionString, $options);

代码示例

您可以在示例文件夹中找到示例。

从 Azure SDK for PHP 迁移

如果您使用 Azure SDK for PHP 访问 Azure 存储服务，我们强烈建议您迁移到本 SDK，以实现更快的问题解决和更快的功能实现。我们正在努力支持最新的服务功能以及改进现有API。

目前，Microsoft Azure Storage PHP客户端库与Azure SDK for PHP中存储块、表、队列和文件API的接口几乎相同。然而，在迁移过程中需要解决一些小的破坏性更改。您可以在BreakingChanges.md中找到详细信息。

需要帮助？

如果您在使用提供的代码时遇到任何问题，请务必查看Microsoft Azure在Stack Overflow上的开发者论坛和github问题。

贡献代码或提供反馈

如果您想成为本项目的积极贡献者，请按照Azure项目贡献指南中的说明操作。您可以在CONTRIBUTING.md中找到更多关于贡献的详细信息。

如果您在库中发现任何错误，请在项目的问题部分提交问题。

microsoft / azure-storage

维护者

详细信息