Использование службы таблиц службы хранилища Azure или Azure Cosmos DB для таблиц из PHP

Мақала
02/07/2024

ОБЛАСТЬ ПРИМЕНЕНИЯ: Таблица

Предупреждение

Этот проект находится на этапе поддержки сообщества в его жизненном цикле. В конечном итоге все связанные клиентские библиотеки будут выведены из эксплуатации безвозвратно. Дополнительные сведения о прекращении поддержки и альтернативах использованию этого проекта см. в разделе Уведомление о прекращении поддержки: клиентские библиотеки PHP службы хранилища Azure.

Совет

Содержимое этой статьи относится к хранилищу таблиц Azure и Azure Cosmos DB для таблицы. API для таблиц — это предложение уровня "Премиум" для хранилища таблиц, которое предлагает оптимизированные для пропускной способности таблицы, глобальное распределение и автоматические вторичные индексы.

В этой статье показано, как создавать таблицы, сохранять данные и выполнять операции CRUD с данными. Выберите службу таблиц Azure или Azure Cosmos DB для таблицы. В приведенных здесь примерах, написанных на PHP, используется клиентская библиотека PHP таблиц службы хранилища Azure. Здесь рассматриваются такие сценарии, как создание и удаление таблицы, а также вставка, удаление и запрашивание сущностей в таблице.

Создание учетной записи службы Azure

Вы можете работать с таблицами, используя хранилище таблиц Azure или Azure Cosmos DB. Дополнительные сведения о различиях между предложениями таблиц в этих двух службах см. в обзоре API для таблиц. Необходимо создать учетную запись для службы, которую вы собираетесь использовать. В следующих разделах показано, как создать и хранилище таблиц Azure, и учетную запись Azure Cosmos DB, однако можно использовать что-то одно.

Хранилище таблиц Azure

Самый простой способ создать учетную запись хранения Azure — воспользоваться порталом Azure. Дополнительную информацию см. в статье Об учетных записях хранения Azure.

Учетную запись хранения Azure можно создать также с помощью Azure PowerShell или Azure CLI.

Если вы не хотите сейчас создавать учетную запись хранения, код можно запустить и протестировать в локальной среде с помощью эмулятора хранения Azure. Дополнительные сведения см. в статье Использование Эмулятора службы хранилища Azure для разработки и тестирования.

Azure Cosmos DB for Table

Инструкции по созданию учетной записи Azure Cosmos DB для таблицы см. в статье Создание учетной записи базы данных.

Создание приложения PHP

Единственным требованием для создания приложения PHP для доступа к службе таблиц хранилища или Azure Cosmos DB для таблицы является ссылка на классы в пакете SDK azure-storage-table для PHP из кода. Можно использовать любые средства разработки для создания приложения, включая программу "Блокнот".

В этом руководстве вы используете хранилище таблиц Azure или Azure Cosmos DB для функций таблиц, которые можно вызывать из приложения PHP. Приложение может выполняться локально или в коде, выполняемом в веб-роли, рабочей роли или веб-сайте Azure.

Получение клиентской библиотеки

Создайте файл с именем composer.json в корневой папке проекта и добавьте в него следующий код:
```
{
"require": {
 "microsoft/azure-storage-table": "*"
}
}
```
Скачайте файл composer.phar в корневой каталог.
Откройте командную строку и выполните следующую команду в корневом каталоге проекта:
```
php composer.phar install
```
Также можно перейти в клиентскую библиотеку таблиц службы хранилища Azure для PHP на GitHub, чтобы клонировать исходный код.

Добавление обязательных ссылок

Чтобы использовать хранилище таблиц службы хранилища Azure или API-интерфейсы Azure Cosmos DB, необходимо указать следующее:

Ссылка на файл автозагрузчика с использованием инструкции require_once и
ссылку на все используемые классы.

В следующем примере показано, как включить файл автозагрузчика и добавить ссылку на класс TableRestProxy.

require_once 'vendor/autoload.php';
use MicrosoftAzure\Storage\Table\TableRestProxy;

В приведенных здесь require_once примерах оператор всегда отображается, но ссылаются только классы, необходимые для выполнения примера.

Добавление строки подключения

Вы можете подключиться либо к учетной записи хранения Azure, либо к учетной записи Azure Cosmos DB для таблицы. Получите строка подключения в зависимости от типа используемой учетной записи.

Добавление подключения к хранилищу таблиц службы хранилища Azure

Для создания экземпляра клиента хранилища таблиц необходимо сначала сформировать правильную строку подключения. Для строки подключения к хранилищу таблиц используется следующий формат:

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

Добавление подключения к эмулятору хранения

Для доступа к эмулятору хранения используйте следующий код:

UseDevelopmentStorage = true

Добавление подключения к Azure Cosmos DB

Для создания экземпляра клиента таблиц Azure Cosmos DB необходимо сначала сформировать правильную строку подключения. Для строки подключения Azure Cosmos DB используется следующий формат:

$connectionString = "DefaultEndpointsProtocol=[https];AccountName=[myaccount];AccountKey=[myaccountkey];TableEndpoint=[https://myendpoint/]";

Для создания клиента хранилища таблиц Azure или клиента Azure Cosmos DB необходимо использовать класс TableRestProxy. Вы можете:

передать строку подключения напрямую или
использовать CloudConfigurationManager (CCM) для проверки нескольких внешних источников на наличие строки подключения:
- по умолчанию предоставляется поддержка одного внешнего источника — переменных среды;
- Можно добавить новые источники, расширив класс ConnectionStringSource.

В приведенных здесь примерах строка подключения передается напрямую.

require_once 'vendor/autoload.php';

use MicrosoftAzure\Storage\Table\TableRestProxy;

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

Создание таблицы

Объект TableRestProxy позволяет создать таблицу с помощью метода createTable. При создании таблицы можно задать время ожидания службы таблиц. Дополнительные сведения о времени ожидания службы таблиц см. в разделе Настройка времени ожидания для операций службы таблиц.

require_once 'vendor\autoload.php';

use MicrosoftAzure\Storage\Table\TableRestProxy;
use MicrosoftAzure\Storage\Common\Exceptions\ServiceException;

// Create Table REST proxy.
$tableClient = TableRestProxy::createTableService($connectionString);

try    {
    // Create table.
    $tableClient->createTable("mytable");
}
catch(ServiceException $e){
    $code = $e->getCode();
    $error_message = $e->getMessage();
    // Handle exception based on error codes and messages.
    // Error codes and messages can be found here:
    // https://learn.microsoft.com/rest/api/storageservices/Table-Service-Error-Codes
}

Дополнительные сведения об ограничениях имен таблиц см. в статье Understanding the Table Service Data Model (Основные сведения о модели данных службы таблиц).

Добавление сущности в таблицу

Чтобы добавить сущность в таблицу, создайте объект сущности и передайте его в TableRestProxy->insertEntity. При создании сущности необходимо указать PartitionKey и RowKey. Эти сущности являются уникальными идентификаторами сущности и представляют собой значения, которые можно запрашивать быстрее, чем другие свойства сущности. Система использует PartitionKey, чтобы автоматически распределять сущности таблицы на несколько узлов хранилища. Сущности с одинаковым значением PartitionKey хранятся на одном узле. Операции с несколькими сущностями, хранящимися на одном узле, выполняются лучше, чем с сущностями, хранящимися на разных узлах. RowKey — это уникальный идентификатор сущности в разделе.

require_once 'vendor/autoload.php';

use MicrosoftAzure\Storage\Table\TableRestProxy;
use MicrosoftAzure\Storage\Common\Exceptions\ServiceException;
use MicrosoftAzure\Storage\Table\Models\Entity;
use MicrosoftAzure\Storage\Table\Models\EdmType;

// Create table REST proxy.
$tableClient = TableRestProxy::createTableService($connectionString);

$entity = new Entity();
$entity->setPartitionKey("tasksSeattle");
$entity->setRowKey("1");
$entity->addProperty("Description", null, "Take out the trash.");
$entity->addProperty("DueDate",
                        EdmType::DATETIME,
                        new DateTime("2012-11-05T08:15:00-08:00"));
$entity->addProperty("Location", EdmType::STRING, "Home");

try{
    $tableClient->insertEntity("mytable", $entity);
}
catch(ServiceException $e){
    // Handle exception based on error codes and messages.
    // Error codes and messages are here:
    // https://learn.microsoft.com/rest/api/storageservices/Table-Service-Error-Codes
    $code = $e->getCode();
    $error_message = $e->getMessage();
}

Дополнительные сведения о типах и свойствах таблиц см. в статье Understanding the Table Service Data Model (Основные сведения о модели данных службы таблиц).

Класс TableRestProxy предлагает два альтернативных способа вставки сущностей: insertOrMergeEntity и insertOrReplaceEntity. Чтобы использовать эти методы, создайте новый объект Entity и передайте его в качестве параметра в любой из этих методов. Каждый метод вставляет сущность, если она не существует. Если сущность уже существует, insertOrMergeEntity обновляет значения свойств, если свойства уже существуют, и добавляет новые свойства, если они не существуют, в то время как insertOrReplaceEntity полностью заменяет существующую сущность. В следующем примере показано, как использовать insertOrMergeEntity. Если сущность с PartitionKey "tasksSeattle" и RowKey "1" еще не существует, эта сущность вставляется. Однако если оно уже существует (как показано в предыдущем примере), DueDate свойство обновляется и Status добавляется. Свойства Description и Location также будут обновлены, однако до таких значений, которые фактически равны предыдущим. Если эти два последних свойства не были добавлены, как показано в примере, но существовали в целевой сущности, их существующие значения останутся неизменными.

require_once 'vendor/autoload.php';

use MicrosoftAzure\Storage\Table\TableRestProxy;
use MicrosoftAzure\Storage\Common\Exceptions\ServiceException;
use MicrosoftAzure\Storage\Table\Models\Entity;
use MicrosoftAzure\Storage\Table\Models\EdmType;

// Create table REST proxy.
$tableClient = TableRestProxy::createTableService($connectionString);

//Create new entity.
$entity = new Entity();

// PartitionKey and RowKey are required.
$entity->setPartitionKey("tasksSeattle");
$entity->setRowKey("1");

// If entity exists, existing properties are updated with new values and
// new properties are added. Missing properties are unchanged.
$entity->addProperty("Description", null, "Take out the trash.");
$entity->addProperty("DueDate", EdmType::DATETIME, new DateTime()); // Modified the DueDate field.
$entity->addProperty("Location", EdmType::STRING, "Home");
$entity->addProperty("Status", EdmType::STRING, "Complete"); // Added Status field.

try    {
    // Calling insertOrReplaceEntity, instead of insertOrMergeEntity as shown,
    // would simply replace the entity with PartitionKey "tasksSeattle" and RowKey "1".
    $tableClient->insertOrMergeEntity("mytable", $entity);
}
catch(ServiceException $e){
    // Handle exception based on error codes and messages.
    // Error codes and messages are here:
    // https://learn.microsoft.com/rest/api/storageservices/Table-Service-Error-Codes
    $code = $e->getCode();
    $error_message = $e->getMessage();
    echo $code.": ".$error_message."<br />";
}

Извлечение одной сущности

С помощью метода TableRestProxy->getEntity можно получить одну сущность, запросив ее ключи PartitionKey и RowKey. В приведенном здесь примере ключ tasksSeattle секции и ключ 1 строки передаются методу getEntity .

require_once 'vendor/autoload.php';

use MicrosoftAzure\Storage\Table\TableRestProxy;
use MicrosoftAzure\Storage\Common\Exceptions\ServiceException;

// Create table REST proxy.
$tableClient = TableRestProxy::createTableService($connectionString);

try    {
    $result = $tableClient->getEntity("mytable", "tasksSeattle", 1);
}
catch(ServiceException $e){
    // Handle exception based on error codes and messages.
    // Error codes and messages are here:
    // https://learn.microsoft.com/rest/api/storageservices/Table-Service-Error-Codes
    $code = $e->getCode();
    $error_message = $e->getMessage();
    echo $code.": ".$error_message."<br />";
}

$entity = $result->getEntity();

echo $entity->getPartitionKey().":".$entity->getRowKey();

Получение всех сущностей в разделе

Запросы сущностей создаются с помощью фильтров. Дополнительные сведения см. в разделе Запросы к таблицам и сущностям. Чтобы получить все сущности в секции, используйте фильтр PartitionKey eq partition_name. В следующем примере показано, как получить все сущности в разделе tasksSeattle, передав фильтр в метод queryEntities.

require_once 'vendor/autoload.php';

use MicrosoftAzure\Storage\Table\TableRestProxy;
use MicrosoftAzure\Storage\Common\Exceptions\ServiceException;

// Create table REST proxy.
$tableClient = TableRestProxy::createTableService($connectionString);

$filter = "PartitionKey eq 'tasksSeattle'";

try    {
    $result = $tableClient->queryEntities("mytable", $filter);
}
catch(ServiceException $e){
    // Handle exception based on error codes and messages.
    // Error codes and messages are here:
    // https://learn.microsoft.com/rest/api/storageservices/Table-Service-Error-Codes
    $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 />";
}

Получение диапазона сущностей в разделе

Процедуру, аналогичную приведенной в предыдущем примере, можно использовать для получения любого подмножества сущностей в разделе. Используемый фильтр определяет подмножество извлекаемых сущностей. Дополнительные сведения см. в разделе Запросы к таблицам и сущностям. В следующем примере показано, как использовать фильтр для получения всех сущностей с определенной LocationDueDate и меньшей указанной датой.

require_once 'vendor/autoload.php';

use MicrosoftAzure\Storage\Table\TableRestProxy;
use MicrosoftAzure\Storage\Common\Exceptions\ServiceException;

// Create table REST proxy.
$tableClient = TableRestProxy::createTableService($connectionString);

$filter = "Location eq 'Office' and DueDate lt '2012-11-5'";

try    {
    $result = $tableClient->queryEntities("mytable", $filter);
}
catch(ServiceException $e){
    // Handle exception based on error codes and messages.
    // Error codes and messages are here:
    // https://learn.microsoft.com/rest/api/storageservices/Table-Service-Error-Codes
    $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 />";
}

Запрос подмножества свойств сущности

Запрос позволяет получить подмножество свойств сущности. Этот метод, который называется проекцией, снижает потребление полосы пропускания и может повысить производительность запросов, особенно для крупных сущностей. Чтобы указать извлекаемое свойство, передайте имя свойства в Query->addSelectField метод . Этот метод можно вызывать несколько раз для добавления дополнительных свойств. После выполнения TableRestProxy->queryEntitiesвозвращаемые сущности будут иметь только выбранные свойства. Если вы хотите вернуть подмножество сущностей Таблицы, используйте фильтр, как показано в предыдущих запросах.

require_once 'vendor/autoload.php';

use MicrosoftAzure\Storage\Table\TableRestProxy;
use MicrosoftAzure\Storage\Common\Exceptions\ServiceException;
use MicrosoftAzure\Storage\Table\Models\QueryEntitiesOptions;

// Create table REST proxy.
$tableClient = TableRestProxy::createTableService($connectionString);

$options = new QueryEntitiesOptions();
$options->addSelectField("Description");

try    {
    $result = $tableClient->queryEntities("mytable", $options);
}
catch(ServiceException $e){
    // Handle exception based on error codes and messages.
    // Error codes and messages are here:
    // https://learn.microsoft.com/rest/api/storageservices/Table-Service-Error-Codes
    $code = $e->getCode();
    $error_message = $e->getMessage();
    echo $code.": ".$error_message."<br />";
}

// All entities in the table are returned, regardless of whether
// they have the Description field.
// To limit the results returned, use a filter.
$entities = $result->getEntities();

foreach($entities as $entity){
    $description = $entity->getProperty("Description")->getValue();
    echo $description."<br />";
}

Обновление сущности

Имеющуюся сущность можно обновить, воспользовавшись методами Entity->setProperty и Entity->addProperty, а затем вызвав TableRestProxy->updateEntity. Следующий пример извлекает сущность, изменяет одно свойство, удаляет другое свойство и добавляет новое свойство. Свойство можно удалить, задав для него значение NULL.

require_once 'vendor/autoload.php';

use MicrosoftAzure\Storage\Table\TableRestProxy;
use MicrosoftAzure\Storage\Common\Exceptions\ServiceException;
use MicrosoftAzure\Storage\Table\Models\Entity;
use MicrosoftAzure\Storage\Table\Models\EdmType;

// Create table REST proxy.
$tableClient = TableRestProxy::createTableService($connectionString);

$result = $tableClient->getEntity("mytable", "tasksSeattle", 1);

$entity = $result->getEntity();
$entity->setPropertyValue("DueDate", new DateTime()); //Modified DueDate.
$entity->setPropertyValue("Location", null); //Removed Location.
$entity->addProperty("Status", EdmType::STRING, "In progress"); //Added Status.

try    {
    $tableClient->updateEntity("mytable", $entity);
}
catch(ServiceException $e){
    // Handle exception based on error codes and messages.
    // Error codes and messages are here:
    // https://learn.microsoft.com/rest/api/storageservices/Table-Service-Error-Codes
    $code = $e->getCode();
    $error_message = $e->getMessage();
    echo $code.": ".$error_message."<br />";
}

Удаление сущности

Чтобы удалить сущность, передайте имя таблицы и ключи сущности PartitionKey и RowKey методу TableRestProxy->deleteEntity.

require_once 'vendor/autoload.php';

use MicrosoftAzure\Storage\Table\TableRestProxy;
use MicrosoftAzure\Storage\Common\Exceptions\ServiceException;

// Create table REST proxy.
$tableClient = TableRestProxy::createTableService($connectionString);

try    {
    // Delete entity.
    $tableClient->deleteEntity("mytable", "tasksSeattle", "2");
}
catch(ServiceException $e){
    // Handle exception based on error codes and messages.
    // Error codes and messages are here:
    // https://learn.microsoft.com/rest/api/storageservices/Table-Service-Error-Codes
    $code = $e->getCode();
    $error_message = $e->getMessage();
    echo $code.": ".$error_message."<br />";
}

При проверке на параллелизм можно задать ETag для удаляемой сущности, воспользовавшись методом DeleteEntityOptions->setEtag и передав объект DeleteEntityOptions в deleteEntity в качестве четвертого параметра.

Пакетные операции с таблицами

С помощью метода TableRestProxy->batch можно выполнять несколько операций в одном запросе. Этот шаблон включает в себя добавление операций в объект BatchRequest и передачу этого объекта методу TableRestProxy->batch. Чтобы добавить операцию в объект BatchRequest , можно вызвать любой из следующих методов несколько раз:

	Описание
`addInsertEntity`	Добавляет операцию insertEntity
`addUpdateEntity`	Добавляет операцию updateEntity
`addMergeEntity`	Добавляет операцию mergeEntity
`addInsertOrReplaceEntity`	Добавляет операцию insertOrReplaceEntity
`addInsertOrMergeEntity`	Добавляет операцию insertOrMergeEntity.
`addDeleteEntity`	Добавление операции deleteEntity

В следующем примере показано, как выполнить операции insertEntity и deleteEntity в одном запросе.

require_once 'vendor/autoload.php';

use MicrosoftAzure\Storage\Table\TableRestProxy;
use MicrosoftAzure\Storage\Common\Exceptions\ServiceException;
use MicrosoftAzure\Storage\Table\Models\Entity;
use MicrosoftAzure\Storage\Table\Models\EdmType;
use MicrosoftAzure\Storage\Table\Models\BatchOperations;

// Configure a connection string for Storage Table service.
$connectionString = "DefaultEndpointsProtocol=[http|https];AccountName=[yourAccount];AccountKey=[yourKey]"

// Create table REST proxy.
$tableClient = TableRestProxy::createTableService($connectionString);

// Create list of batch operation.
$operations = new BatchOperations();

$entity1 = new Entity();
$entity1->setPartitionKey("tasksSeattle");
$entity1->setRowKey("2");
$entity1->addProperty("Description", null, "Clean roof gutters.");
$entity1->addProperty("DueDate",
                        EdmType::DATETIME,
                        new DateTime("2012-11-05T08:15:00-08:00"));
$entity1->addProperty("Location", EdmType::STRING, "Home");

// Add operation to list of batch operations.
$operations->addInsertEntity("mytable", $entity1);

// Add operation to list of batch operations.
$operations->addDeleteEntity("mytable", "tasksSeattle", "1");

try    {
    $tableClient->batch($operations);
}
catch(ServiceException $e){
    // Handle exception based on error codes and messages.
    // Error codes and messages are here:
    // https://learn.microsoft.com/rest/api/storageservices/Table-Service-Error-Codes
    $code = $e->getCode();
    $error_message = $e->getMessage();
    echo $code.": ".$error_message."<br />";
}

Дополнительные сведения о пакетной обработке операций с таблицами см. в статье Performing Entity Group Transactions (Выполнение транзакций для группы сущностей).

Удаление таблицы

Наконец, чтобы удалить таблицу, передайте ее имя методу TableRestProxy->deleteTable.

require_once 'vendor/autoload.php';

use MicrosoftAzure\Storage\Table\TableRestProxy;
use MicrosoftAzure\Storage\Common\Exceptions\ServiceException;

// Create table REST proxy.
$tableClient = TableRestProxy::createTableService($connectionString);

try    {
    // Delete table.
    $tableClient->deleteTable("mytable");
}
catch(ServiceException $e){
    // Handle exception based on error codes and messages.
    // Error codes and messages are here:
    // https://learn.microsoft.com/rest/api/storageservices/Table-Service-Error-Codes
    $code = $e->getCode();
    $error_message = $e->getMessage();
    echo $code.": ".$error_message."<br />";
}

Обозреватель хранилищ Microsoft Azure — это бесплатное автономное приложение от корпорации Майкрософт, позволяющее визуализировать данные из службы хранилища Azure на платформе Windows, macOS и Linux.
Центр разработчиков PHP

Бөлісу құралы:

Использование службы таблиц службы хранилища Azure или Azure Cosmos DB для таблиц из PHP

Создание учетной записи службы Azure

Хранилище таблиц Azure

Azure Cosmos DB for Table

Создание приложения PHP

Получение клиентской библиотеки

Добавление обязательных ссылок

Добавление строки подключения

Добавление подключения к хранилищу таблиц службы хранилища Azure

Добавление подключения к эмулятору хранения

Добавление подключения к Azure Cosmos DB

Создание таблицы

Добавление сущности в таблицу

Извлечение одной сущности

Получение всех сущностей в разделе

Получение диапазона сущностей в разделе

Запрос подмножества свойств сущности

Обновление сущности

Удаление сущности

Пакетные операции с таблицами

Удаление таблицы

Қосымша ресурстар

Бөлісу құралы:

Использование службы таблиц службы хранилища Azure или Azure Cosmos DB для таблиц из PHP

Создание учетной записи службы Azure

Хранилище таблиц Azure

Azure Cosmos DB for Table

Создание приложения PHP

Получение клиентской библиотеки

Добавление обязательных ссылок

Добавление строки подключения

Добавление подключения к хранилищу таблиц службы хранилища Azure

Добавление подключения к эмулятору хранения

Добавление подключения к Azure Cosmos DB

Создание таблицы

Добавление сущности в таблицу

Извлечение одной сущности

Получение всех сущностей в разделе

Получение диапазона сущностей в разделе

Запрос подмножества свойств сущности

Обновление сущности

Удаление сущности

Пакетные операции с таблицами

Удаление таблицы

См. также

Қосымша ресурстар