cristopherm/windowsazure

v0.5.9 2020-08-12 16:37 UTC

README

Build Status Latest Stable Version

Microsoft Azure SDK for PHP

本项目提供一组PHP客户端库,使您能够轻松访问Microsoft Azure的表、Blob、队列、服务总线(队列和主题)、服务运行时和服务管理API。有关如何在Microsoft Azure上托管PHP应用程序的文档,请参阅Microsoft Azure PHP开发者中心

功能

  • Blob
    • 创建、列出和删除容器,处理容器元数据和权限,列出容器中的Blob
    • 创建块和页面Blob(从流或字符串),处理Blob块和页面,删除Blob
    • 处理Blob属性、元数据、租约,快照Blob
    • REST API版本:请参阅https://github.com/Azure/azure-storage-php
  • 存储队列
  • 服务总线
    • 队列:创建、列出和删除队列;发送、接收、解锁和删除消息
    • 主题:创建、列出和删除主题;创建、列出和删除订阅;发送、接收、解锁和删除消息;创建、列出和删除规则
  • 服务运行时
    • 发现其他角色实例端点的地址和端口
    • 获取配置设置和访问本地资源
    • 获取当前角色和其他角色实例的信息
    • 查询和设置当前角色的状态
    • REST API版本:2011-03-08
  • 服务管理
    • 存储账户:创建、更新、删除、列出、重新生成密钥
    • 亲和组:创建、更新、删除、列出、获取属性
    • 位置:列出
    • 托管服务:创建、更新、删除、列出、获取属性
    • 部署:创建、获取、删除、交换、更改配置、更新状态、升级、回滚
    • 角色实例:重启、重映像
    • REST API版本:2011-10-01
  • 媒体服务
    • 连接
    • 导入资产,上传文件
    • 编码/处理资产,创建作业,作业模板
    • 管理媒体服务实体:创建/更新/读取/删除/获取列表
    • 交付SAS和流式媒体内容
    • 动态加密:带有和没有令牌限制的AES和DRM(PlayReady/Widevine/FairPlay)
    • 缩放编码保留单元类型
    • 实时流媒体:实时编码和透传通道、程序及其所有操作
    • REST API版本:2.13

入门

下载源代码

要从GitHub获取源代码,请在项目根目录下输入以下命令

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

注意

解决依赖项的推荐方式是使用Composer包管理器安装它们。

通过Composer安装

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

    {
        "require": {
            "microsoft/windowsazure": "^0.5"
        }
    }
  • 在项目根目录下下载composer.phar

  • 打开命令提示符,并在项目根目录下执行以下命令

    php composer.phar install
    

    注意

    在Windows上,您还需要将Git可执行文件添加到PATH环境变量中。

使用方法

入门

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

  • 首先,包含自动加载脚本

    require_once "vendor/autoload.php";
  • 包含你将要使用的命名空间。

    要创建任何Microsoft Azure服务客户端,你需要使用ServicesBuilder

    use WindowsAzure\Common\ServicesBuilder;

    要处理异常,你需要

    use WindowsAzure\Common\ServiceException;
  • 要实例化服务客户端,你还需要一个有效的连接字符串。格式为

    • 要访问实时存储服务(表、块、队列)

      DefaultEndpointsProtocol=[http|https];AccountName=[yourAccount];AccountKey=[yourKey]
      
    • 要访问模拟存储

      UseDevelopmentStorage=true
      
    • 要访问服务总线

      Endpoint=[yourEndpoint];SharedSecretIssuer=[yourWrapAuthenticationName];SharedSecretValue=[yourWrapPassword]
      

      其中端点通常是以下格式:https://[你的命名空间].servicebus.windows.net

    • 要访问服务管理API

      SubscriptionID=[yourSubscriptionId];CertificatePath=[filePathToYourCertificate]
      
  • 实例化一个“REST代理”——它是围绕给定服务的可用调用包装器。

    • 对于存储服务

      $tableRestProxy = ServicesBuilder::getInstance()->createTableService($connectionString);
      $blobRestProxy = ServicesBuilder::getInstance()->createBlobService($connectionString);
      $queueRestProxy = ServicesBuilder::getInstance()->createQueueService($connectionString);
    • 对于服务总线

      $serviceBusRestProxy = ServicesBuilder::getInstance()->createServiceBusService($connectionString);
    • 对于服务管理

      $serviceManagementRestProxy = ServicesBuilder::getInstance()->createServiceManagementService($connectionString);
    • 对于媒体服务

      // 1 - Instantiate the credentials
      $credentials = new AzureAdTokenCredentials(
          '<tenant domain name>',
          new AzureAdClientSymmetricKey('<service principal client id>', '<service principal client key>'),
          AzureEnvironments::AZURE_CLOUD_ENVIRONMENT());
      
      // 2 - Instantiate a token provider
      $provider = new AzureAdTokenProvider($credentials);
      
      // 3 - Connect to Azure Media Services
      $mediaServicesRestProxy = ServicesBuilder::getInstance()->createMediaServicesService(new MediaServicesSettings('<rest api endpoint>', $provider));

      你可以在示例文件夹中找到关于媒体服务身份验证的更多示例。

表存储

以下是在使用表服务执行的一些常见操作示例。更多内容请参阅如何使用表服务

创建一个表

要创建一个表,调用createTable

try {
  // Create table.
  $tableRestProxy->createTable("mytable");
} catch(ServiceException $e){
  $code = $e->getCode();
  $error_message = $e->getMessage();
  echo $code.": ".$error_message."<br />";
}

表的错误代码和消息

插入实体

要将实体添加到表,创建一个新的Entity对象并将其传递给TableRestProxy>insertEntity。请注意,在创建实体时,你必须指定一个PartitionKeyRowKey。这些是实体的唯一标识符,并且是查询速度比其他实体属性快的值。系统使用PartitionKey自动将表实体分布到许多存储节点。

use MicrosoftAzure\Storage\Table\Models\Entity;
use MicrosoftAzure\Storage\Table\Models\EdmType;

$entity = new Entity();
$entity->setPartitionKey("pk");
$entity->setRowKey("1");
$entity->addProperty("PropertyName", EdmType::STRING, "Sample");

try{
  $tableRestProxy->insertEntity("mytable", $entity);
} catch(ServiceException $e){
  $code = $e->getCode();
  $error_message = $e->getMessage();
  echo $code.": ".$error_message."<br />";
}

查询实体

要查询实体,可以调用queryEntities。你检索的实体子集将由你使用的过滤器确定(有关更多信息,请参阅查询表和实体)。你也可以完全不提供过滤器。

$filter = "RowKey eq '2'";

try {
  $result = $tableRestProxy->queryEntities("mytable", $filter);
} catch(ServiceException $e){
  $code = $e->getCode();
  $error_message = $e->getMessage();
  echo $code.": ".$error_message."<br />";
}

$entities = $result->getEntities();

foreach($entities as $entity){
  echo $entity->getPartitionKey().":".$entity->getRowKey()."<br />";
}

块存储

要开始使用Blob服务,你必须包含BlobServiceBlobSettings命名空间,并设置ACCOUNT_NAMEACCOUNT_KEY配置设置以进行身份验证。然后,使用BlobService工厂实例化包装器。

以下是在使用Blob服务执行的一些常见操作示例。更多内容请参阅如何使用Blob服务

创建一个容器

// OPTIONAL: Set public access policy and metadata.
// Create container options object.
$createContainerOptions = new CreateContainerOptions();

// Set public access policy. Possible values are
// PublicAccessType::CONTAINER_AND_BLOBS and PublicAccessType::BLOBS_ONLY.
// CONTAINER_AND_BLOBS: full public read access for container and blob data.
// BLOBS_ONLY: public read access for blobs. Container data not available.
// If this value is not specified, container data is private to the account owner.
$createContainerOptions->setPublicAccess(PublicAccessType::CONTAINER_AND_BLOBS);

// Set container metadata
$createContainerOptions->addMetaData("key1", "value1");
$createContainerOptions->addMetaData("key2", "value2");

try {
  // Create container.
  $blobRestProxy->createContainer("mycontainer", $createContainerOptions);
} catch(ServiceException $e){
  $code = $e->getCode();
  $error_message = $e->getMessage();
  echo $code.": ".$error_message."<br />";
}

Blob的错误代码和消息

有关容器ACL的更多信息,请参阅设置容器ACL(REST API)

上传一个Blob

要将文件作为Blob上传,使用BlobRestProxy>createBlockBlob方法。此操作将在Blob不存在时创建它,如果已存在则覆盖它。下面的代码示例假设容器已创建,并使用fopen将文件作为流打开。

$content = fopen("myfile.txt", "r");
$blob_name = "myblob";

try {
  //Upload blob
  $blobRestProxy->createBlockBlob("mycontainer", $blob_name, $content);
} catch(ServiceException $e){
  $code = $e->getCode();
  $error_message = $e->getMessage();
  echo $code.": ".$error_message."<br />";
}

虽然上面的示例将Blob作为流上传,但Blob也可以作为字符串上传。

列出容器中的Blob

要列出容器中的Blob,使用带有foreach循环的BlobRestProxy>listBlobs方法来遍历结果。以下代码输出容器中每个Blob的名称和URI。

try {
  // List blobs.
  $blob_list = $blobRestProxy->listBlobs("mycontainer");
  $blobs = $blob_list->getBlobs();

  foreach($blobs as $blob)
  {
    echo $blob->getName().": ".$blob->getUrl()."<br />";
  }
} catch(ServiceException $e){
  $code = $e->getCode();
  $error_message = $e->getMessage();
  echo $code.": ".$error_message."<br />";
}

存储队列

要开始使用队列服务,你必须包含QueueServiceQueueSettings命名空间,并设置ACCOUNT_NAMEACCOUNT_KEY配置设置以进行身份验证。然后,使用QueueService工厂实例化包装器。

以下是在使用队列服务执行的一些常见操作示例。更多内容请参阅如何使用队列服务

创建队列

使用 QueueRestProxy 对象,您可以通过 createQueue 方法创建队列。在创建队列时,您可以设置队列上的选项,但这不是必需的。

$createQueueOptions = new CreateQueueOptions();
$createQueueOptions->addMetaData("key1", "value1");
$createQueueOptions->addMetaData("key2", "value2");

try {
  // Create queue.
  $queueRestProxy->createQueue("myqueue", $createQueueOptions);
} catch(ServiceException $e){
  $code = $e->getCode();
  $error_message = $e->getMessage();
  echo $code.": ".$error_message."<br />";
}

队列的错误代码和消息

向队列添加消息

要向队列添加消息,请使用 QueueRestProxy->createMessage。该方法接受队列名称、消息文本和消息选项(这些选项是可选的)。为了与其他系统兼容,您可能需要将消息进行 base64 编码。

try {
  // Create message.
  $msg = "Hello World!";
  // optional: $msg = base64_encode($msg);
  $queueRestProxy->createMessage("myqueue", $msg);
} catch(ServiceException $e){
  $code = $e->getCode();
  $error_message = $e->getMessage();
  echo $code.": ".$error_message."<br />";
}

查看下一个消息

您可以通过调用 QueueRestProxy->peekMessages 来查看队列前面的消息(或消息),而不从队列中删除它。

// OPTIONAL: Set peek message options.
$message_options = new PeekMessagesOptions();
$message_options->setNumberOfMessages(1); // Default value is 1.

try {
  $peekMessagesResult = $queueRestProxy->peekMessages("myqueue", $message_options);
} catch(ServiceException $e){
  $code = $e->getCode();
  $error_message = $e->getMessage();
  echo $code.": ".$error_message."<br />";
}

$messages = $peekMessagesResult->getQueueMessages();

// View messages.
$messageCount = count($messages);
if($messageCount <= 0){
  echo "There are no messages.<br />";
}
else{
  foreach($messages as $message)  {
    echo "Peeked message:<br />";
    echo "Message Id: ".$message->getMessageId()."<br />";
    echo "Date: ".date_format($message->getInsertionDate(), 'Y-m-d')."<br />";
    echo "Message text: ".$message->getMessageText()."<br /><br />";
  }
}

移除下一个消息

您的代码通过两个步骤从队列中移除消息。首先,您调用 QueueRestProxy->listMessages,这使得消息对任何其他从队列中读取的代码不可见。默认情况下,此消息将保持不可见 30 秒(如果在此期间未删除消息,它将再次在队列中可见)。为了完成从队列中删除消息,您必须调用 QueueRestProxy->deleteMessage

// Get message.
$listMessagesResult = $queueRestProxy->listMessages("myqueue");
$messages = $listMessagesResult->getQueueMessages();
$message = $messages[0];

// Process message

// Get message Id and pop receipt.
$messageId = $message->getMessageId();
$popReceipt = $message->getPopReceipt();

try {
  // Delete message.
  $queueRestProxy->deleteMessage("myqueue", $messageId, $popReceipt);
} catch(ServiceException $e){
  $code = $e->getCode();
  $error_message = $e->getMessage();
  echo $code.": ".$error_message."<br />";
}

服务总线队列

当前 PHP 服务总线 API 只支持 ACS 连接字符串。目前您需要使用 PowerShell 创建新的 ACS 服务总线命名空间。首先,请确保您已安装 Azure PowerShell,然后在 PowerShell 命令提示符下运行以下命令

Add-AzureAccount # this will sign you in
New-AzureSBNamespace -CreateACSNamespace $true -Name 'mytestbusname' -Location 'West US' -NamespaceType 'Messaging'

如果成功,您将在 PowerShell 输出中获取连接字符串。如果使用它时遇到连接错误,并且连接字符串看起来像 Endpoint=sb://...,请将其更改为 Endpoint=https://...

创建队列

try {
  $queueInfo = new QueueInfo("myqueue");

  // Create queue.
  $serviceBusRestProxy->createQueue($queueInfo);
} catch(ServiceException $e){
  $code = $e->getCode();
  $error_message = $e->getMessage();
  echo $code.": ".$error_message."<br />";
}

错误代码和消息

发送消息

要将消息发送到服务总线队列,您的应用程序将调用 ServiceBusRestProxy->sendQueueMessage 方法。发送到(和从)服务总线队列的消息是 BrokeredMessage 类的实例。

try {
  // Create message.
  $message = new BrokeredMessage();
  $message->setBody("my message");

  // Send message.
  $serviceBusRestProxy->sendQueueMessage("myqueue", $message);
} catch(ServiceException $e){
  $code = $e->getCode();
  $error_message = $e->getMessage();
  echo $code.": ".$error_message."<br />";
}

接收消息

从队列接收消息的主要方式是使用 ServiceBusRestProxy->receiveQueueMessage 方法。消息可以通过两种不同的模式接收:ReceiveAndDelete(在读取时标记消息为已消费)和 PeekLock(锁定消息一段时间,但不删除)。

以下示例演示了如何使用 PeekLock 模式(非默认模式)接收和加工消息。

try {
  // Set the receive mode to PeekLock (default is ReceiveAndDelete).
  $options = new ReceiveMessageOptions();
  $options->setPeekLock(true);

  // Receive message.
  $message = $serviceBusRestProxy->receiveQueueMessage("myqueue", $options);
  echo "Body: ".$message->getBody()."<br />";
  echo "MessageID: ".$message->getMessageId()."<br />";

  // *** Process message here ***

  // Delete message.
  $serviceBusRestProxy->deleteMessage($message);
} catch(ServiceException $e){
  $code = $e->getCode();
  $error_message = $e->getMessage();
  echo $code.": ".$error_message."<br />";
}

服务总线主题

创建主题

try {
  // Create topic.
  $topicInfo = new TopicInfo("mytopic");
  $serviceBusRestProxy->createTopic($topicInfo);
} catch(ServiceException $e){
  $code = $e->getCode();
  $error_message = $e->getMessage();
  echo $code.": ".$error_message."<br />";
}

使用默认(MatchAll)过滤器创建订阅

try {
  // Create subscription.
  $subscriptionInfo = new SubscriptionInfo("mysubscription");
  $serviceBusRestProxy->createSubscription("mytopic", $subscriptionInfo);
} catch(ServiceException $e){
  $code = $e->getCode();
  $error_message = $e->getMessage();
  echo $code.": ".$error_message."<br />";
}

向主题发送消息

发送到服务总线主题的消息是 BrokeredMessage 类的实例。

try {
  // Create message.
  $message = new BrokeredMessage();
  $message->setBody("my message");

  // Send message.
  $serviceBusRestProxy->sendTopicMessage("mytopic", $message);
} catch(ServiceException $e){
  $code = $e->getCode();
  $error_message = $e->getMessage();
  echo $code.": ".$error_message."<br />";
}

从主题接收消息

从订阅接收消息的主要方式是使用 ServiceBusRestProxy->receiveSubscriptionMessage 方法。接收到的消息可以以两种不同的模式工作:ReceiveAndDelete(默认)和类似于服务总线队列的 PeekLock

以下示例演示了如何使用 ReceiveAndDelete 模式(默认模式)接收和加工消息。

try {
  // Set receive mode to PeekLock (default is ReceiveAndDelete)
  $options = new ReceiveMessageOptions();
  $options->setReceiveAndDelete();

  // Get message.
  $message = $serviceBusRestProxy->receiveSubscriptionMessage("mytopic",
                                "mysubscription",
                                $options);
  echo "Body: ".$message->getBody()."<br />";
  echo "MessageID: ".$message->getMessageId()."<br />";
} catch(ServiceException $e){
  $code = $e->getCode();
  $error_message = $e->getMessage();
  echo $code.": ".$error_message."<br />";
}

服务管理

设置证书

您需要创建两个证书,一个用于服务器(.cer 文件)和一个用于客户端(.pem 文件)。要使用 OpenSSL 创建 .pem 文件,执行以下命令

openssl req -x509 -nodes -days 365 -newkey rsa:1024 -keyout mycert.pem -out mycert.pem

要创建 .cer 证书,执行以下命令

openssl x509 -inform pem -in mycert.pem -outform der -out mycert.cer

列出可用位置

$serviceManagementRestProxy->listLocations();
$locations = $result->getLocations();
foreach($locations as $location){
      echo $location->getName()."<br />";
}

创建存储服务

要创建存储服务,您需要一个服务名称(介于 3 到 24 个小写字母之间,在 Microsoft Azure 中唯一),一个标签(服务的 base-64 编码名称,最多 100 个字符),以及一个位置或亲和组。为服务提供描述是可选的。

$name = "mystorageservice";
$label = base64_encode($name);
$options = new CreateStorageServiceOptions();
$options->setLocation('West US');

$result = $serviceManagementRestProxy->createStorageService($name, $label, $options);

创建云服务

云服务也称为托管服务(来自早期版本的Microsoft Azure)。createHostedServices方法允许您通过提供托管服务名称(在Microsoft Azure中必须是唯一的)、标签(基础64编码的托管服务名称)以及一个允许您设置服务位置或亲和组的CreateServiceOptions对象来创建一个新的托管服务。

$name = "myhostedservice";
$label = base64_encode($name);
$options = new CreateServiceOptions();
$options->setLocation('West US');
// Instead of setLocation, you can use setAffinityGroup to set an affinity group.

$result = $serviceManagementRestProxy->createHostedService($name, $label, $options);

创建部署

要将新部署到Azure,您必须将包文件存储在同一个订阅下的Microsoft Azure Blob存储账户中,该订阅与要上传包的托管服务相同。您可以使用Microsoft Azure PowerShell cmdletscspack命令行工具创建部署包。

$hostedServiceName = "myhostedservice";
$deploymentName = "v1";
$slot = DeploymentSlot::PRODUCTION;
$packageUrl = "URL_for_.cspkg_file";
$configuration = file_get_contents('path_to_.cscfg_file');
$label = base64_encode($hostedServiceName);

$result = $serviceManagementRestProxy->createDeployment($hostedServiceName,
                         $deploymentName,
                         $slot,
                         $packageUrl,
                         $configuration,
                         $label);

$status = $serviceManagementRestProxy->getOperationStatus($result);
echo "Operation status: ".$status->getStatus()."<br />";

媒体服务

使用文件创建新资产

要使用文件创建资产,您需要创建一个空资产,创建具有写权限的访问策略,创建一个连接您的资产和访问策略的定位器,执行实际的上传并生成文件信息。

$asset = new Asset(Asset::OPTIONS_NONE);
$asset = $restProxy->createAsset($asset);

$access = new AccessPolicy('[Some access policy name]');
$access->setDurationInMinutes([Munites AccessPolicy is valid]);
$access->setPermissions(AccessPolicy::PERMISSIONS_WRITE);
$access = $restProxy->createAccessPolicy($access);

$sasLocator = new Locator($asset,  $access, Locator::TYPE_SAS);
$sasLocator->setStartTime(new \DateTime('now -5 minutes'));
$sasLocator = $restProxy->createLocator($sasLocator);

$restProxy->uploadAssetFile($sasLocator, '[file name]', '[file content]');
$restProxy->createFileInfos($asset);

编码资产

要执行媒体文件编码,您需要一个包含文件的输入资产(如前一章所示)。您还需要创建一个任务数据对象数组和作业数据对象。要创建任务对象,请使用媒体处理器、任务XML正文和配置名称。

$mediaProcessor = $this->restProxy->getLatestMediaProcessor('[Media processor]');

$task = new Task('[Task XML body]', $mediaProcessor->getId(), TaskOptions::NONE);
$task->setConfiguration('[Configuration name]');

$restProxy->createJob(new Job(), array($inputAsset), array($task));

获取编码资产的公共URL

在您上传了媒体文件并对其实施编码后,您可以获取该文件的下载URL或多个比特率文件的流URL。创建一个新的具有读权限的访问策略,并通过定位器将其链接到作业输出资产。

$accessPolicy = new AccessPolicy('[Some access policy name]');
$accessPolicy->setDurationInMinutes([Munites AccessPolicy is valid]);
$accessPolicy->setPermissions(AccessPolicy::PERMISSIONS_READ);
$accessPolicy = $restProxy->createAccessPolicy($accessPolicy);

// Download URL
$sasLocator = new Locator($asset, $accessPolicy, Locator::TYPE_SAS);
$sasLocator->setStartTime(new \DateTime('now -5 minutes'));
$sasLocator = $restProxy->createLocator($sasLocator);

// Azure needs time to publish media
sleep(30);

$downloadUrl = $sasLocator->getBaseUri() . '/' . '[File name]' . $sasLocator->getContentAccessComponent()

// Streaming URL
$originLocator = new Locator($asset, $accessPolicy, Locator::TYPE_ON_DEMAND_ORIGIN);
$originLocator = $restProxy->createLocator($originLocator);

// Azure needs time to publish media
sleep(30);

$streamingUrl = $originLocator->getPath() . '[Manifest file name]' . "/manifest";

管理媒体服务实体

媒体服务的CRUD操作通过媒体服务REST代理类执行。它具有“创建资产”、“创建定位器”、“创建作业”等创建实体的方法。

要检索所有实体列表,您可以使用“getAssetList”、“getAccessPolicyList”、“getLocatorList”、“getJobList”等方法。要获取单个实体数据,请使用“getAsset”、“getJob”、“getTask”等方法,传递实体标识符或具有非空标识符的实体数据模型对象作为参数。

使用“updateLocator”、“updateAsset”、“updateAssetFile”等方法更新实体,传递实体数据模型对象作为参数。在数据模型对象中指定有效的实体标识符非常重要。

使用“deleteAsset”、“deleteAccessPolicy”、“deleteJob”等方法删除实体,传递实体标识符或具有非空标识符的实体数据模型对象作为参数。

您还可以使用“getAssetLocators”、“getAssetParentAssets”、“getAssetStorageAccount”、“getLocatorAccessPolicy”、“getJobTasks”等方法获取关联实体,传递实体标识符或具有非空标识符的实体数据模型对象作为参数。

您可以在IMediaServices接口中找到所有可用方法的完整列表。

有关更多示例,请参阅Microsoft Azure PHP开发者中心

需要帮助?

如果您在提供的代码中遇到任何问题,请务必查看Microsoft Azure在Stack Overflow上的开发者论坛

贡献代码或提供反馈

如果您想成为该项目的积极贡献者,请遵循Microsoft Azure项目贡献指南中提供的说明。

要设置您的开发环境,请遵循本wiki页面中的说明。

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

了解更多信息

微软Azure PHP开发者中心

本项目采用了微软开源行为准则。如需更多信息,请参阅行为准则常见问题解答,或通过opencode@microsoft.com联系,以提出任何额外的问题或评论。