README

这是一个从 https://github.com/Azure/azure-storage-php 克隆的版本，已修改以支持 php 5.5。

Microsoft Azure Storage PHP 客户端库

此项目提供了一套 PHP 客户端库，可轻松访问 Microsoft Azure Storage 服务（Blob、表、队列和文件）。有关如何在 Microsoft Azure 上托管 PHP 应用程序的文档，请参阅 Microsoft Azure PHP 开发中心。

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

注意

如果您正在寻找 Service Bus、Service Runtime、Service Management 或 Media Services 库，请访问 https://github.com/Azure/azure-sdk-for-php。

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

特性

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

请参阅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

用法

在使用库调用任何 Microsoft Azure 存储 API 之前，必须执行以下四个基本步骤。

首先，包含自动加载脚本

require_once "vendor/autoload.php";

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

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

use MicrosoftAzureLegacy\Storage\Blob\BlobRestProxy;

要处理异常，您需要

use MicrosoftAzureLegacy\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 身份验证。

使用中间件

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

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

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

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

用户可以创建继承自 MicrosoftAzureLegacy\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 状态码 403 和 404）不会重试。

重试类型

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 中存储 blob、表、队列和文件 API 几乎具有相同的接口。然而，在迁移过程中需要解决一些细微的破坏性变化。您可以在BreakingChanges.md中找到详细信息。

需要帮助？

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

贡献代码或提供反馈

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

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

aivanov-dev / azure-storage-legacy-php

维护者

详细信息