Como usar o serviço de Tabela de Armazenamento do Microsoft Azure ou o Azure Cosmos DB for Table do PHP

APLICA-SE A: Tabela

Aviso

Este projeto está no estágio de suporte da comunidade do ciclo de vida dele. Eventualmente, todas as bibliotecas de cliente associadas serão desativadas permanentemente. Para obter mais informações sobre a desativação e as alternativas ao uso desse projeto, consulte Aviso de desativação : bibliotecas de clientes PHP do Armazenamento do Azure.

Dica

O conteúdo deste artigo se aplica ao Armazenamento de Tabelas do Azure e ao Azure Cosmos DB for Table. A API para Tabela é uma oferta premium para armazenamento de tabelas que oferece tabelas com otimização de taxa de transferência, distribuição global e índices secundários automáticos.

Este artigo mostra como criar tabelas, armazenar dados e realizar operações CRUD nos dados. Escolha o serviço de Tabela do Azure ou o Azure Cosmos DB for Table. Os exemplos são escritos em PHP e usam a Biblioteca do Cliente de PHP da Tabela Armazenamento do Azure. Os cenários abrangidos incluem criar e excluir uma tabela e inserir, excluir e consultar entidades em uma tabela.

Criar conta de serviço do Azure

Você pode trabalhar com tabelas usando o Armazenamento de Tabelas do Azure ou o Azure Cosmos DB. Para saber mais sobre as diferenças entre as ofertas de tabela desses dois serviços, confira a Visão geral da API para tabela. Você precisa criar uma conta para o serviço que você vai usar. As seções a seguir mostram como criar as contas do Armazenamento de Tabelas do Azure e do Azure Cosmos DB, no entanto, você pode usar apenas um deles.

Armazenamento de Tabelas do Azure

A maneira mais fácil de criar uma conta de armazenamento do Azure é usando o portal do Azure. Para saber mais, consulte Criar uma conta de armazenamento.

Você também pode criar uma conta de armazenamento do Azure usando o Azure PowerShell ou a CLI do Azure.

Se você preferir não criar uma conta de armazenamento no momento, também poderá usar o Emulador de Armazenamento do Azure para executar e testar o seu código em um ambiente local. Para saber mais, confira Usar o Emulador de Armazenamento do Azure para desenvolvimento e teste.

Azure Cosmos DB for Table

Para obter instruções sobre como criar uma conta do Azure Cosmos DB for Table, veja Criar uma conta de banco de dados.

Criar um aplicativo PHP

O único requisito para criar um aplicativo PHP para acessar o serviço de tabela de armazenamento ou o Azure Cosmos DB for Table é fazer referência às classes no SDK do azure-storage-table para PHP de dentro do seu código. Você pode usar as ferramentas de desenvolvimento para criar seu aplicativo, incluindo o bloco de notas.

Neste guia, você usa o Armazenamento de Tabelas do Azure ou os recursos do Azure Cosmos DB for Table que podem ser chamados de dentro de um aplicativo PHP. O aplicativo pode ser executado localmente ou no código em execução em uma função Web do Azure, função de trabalho ou site.

Obter a biblioteca de cliente

1. Crie um arquivo chamado composer.json na raiz do seu projeto e adicione o seguinte código a ele:

   {
   "require": {
    "microsoft/azure-storage-table": "*"
   }
   }
   

2. Baixe composer.phar na sua raiz.

3. Abra um prompt de comando e execute o seguinte comando na raiz do projeto:

   php composer.phar install
   

   Como alternativa, acesse a biblioteca de clientes PHP da Tabela de Armazenamento do Azure no GitHub para clonar o código-fonte.

Adicionar as referências necessárias

Para usar o serviço de Tabela de Armazenamento ou APIs do Azure Cosmos DB, você deve:

• Fazer referência ao arquivo de carregador automático usando a instrução require_once, e
• Fazer referência a qualquer classe que você usa.

O exemplo a seguir mostra como incluir o arquivo de carregador automático e fazer referência à classe TableRestProxy.

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

Nos exemplos aqui, a require_once instrução é sempre mostrada, mas somente as classes necessárias para o exemplo a ser executado são referenciadas.

Adicionar sua cadeia de conexão

Você pode se conectar à conta de armazenamento do Azure ou à conta do Azure Cosmos DB for Table. Obtenha o cadeia de conexão com base no tipo de conta que você está usando.

Adicionar uma conexão de serviço de Tabela de Armazenamento

Para criar uma instância de um cliente de serviço Tabela de Armazenamento, você deve primeiramente ter uma cadeia de conexão válida. O formato da cadeia de conexão do serviço Tabela de Armazenamento é:

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

Adicionar uma conexão do Emulador de Armazenamento

Para acessar o emulador de Armazenamento:

UseDevelopmentStorage = true

Adicionar uma conexão do Azure Cosmos DB

Para criar uma instância de um cliente de Tabela do Azure Cosmos DB, você deve primeiramente ter uma cadeia de conexão válida. O formato para a cadeia de conexão do Azure Cosmos DB é:

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

Para criar um cliente do serviço de tabela do Azure ou o cliente do Azure Cosmos DB, você precisa usar a classe TableRestProxy. Você pode:

• Passar a cadeia de conexão diretamente para ele ou
• Usar CloudConfigurationManager (CCM) para verificar várias fontes externas da cadeia de conexão:
  • Por padrão, ele é fornecido com suporte para uma fonte externa – variáveis de ambiente.
  • Você pode adicionar novas origens estendendo a classe ConnectionStringSource.

Para os exemplos descritos aqui, a cadeia de conexão é passada diretamente.

require_once 'vendor/autoload.php';

use MicrosoftAzure\Storage\Table\TableRestProxy;

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

Criar uma tabela

O objeto TableRestProxy permite que você crie uma tabela com o método createTable. Ao criar uma tabela, você pode definir o tempo limite do serviço Tabela. Para obter mais informações sobre o tempo limite do serviço Tabela, consulte Configurando tempos limite para operações de serviço de tabela.

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
}

Para obter informações sobre restrições em nomes de tabela, confira Noções básicas sobre o modelo de dados do serviço Tabela.

Adicionar uma entidade a uma tabela

Para adicionar uma entidade a uma tabela, crie um novo objeto Entidade e passá-lo para TableRestProxy->insertEntity. Ao criar uma entidade, você deve especificar um PartitionKey e RowKey. Essas entidades são os identificadores exclusivos de uma entidade e são valores que podem ser consultados mais rapidamente do que outras propriedades de entidade. O sistema usa PartitionKey para distribuir automaticamente as entidades das tabelas por vários nós de Armazenamento. As entidades com a mesma PartitionKey são armazenadas no mesmo nó. As operações em várias entidades armazenadas no mesmo nó têm um desempenho melhor do que em entidades armazenadas em nós diferentes. RowKey é a ID exclusiva de uma entidade dentro de uma partição.

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();
}

Para obter informações sobre tipos e propriedades de Tabela, confira Noções básicas sobre o modelo de dados do serviço Tabela.

A classe TableRestProxy oferece dois métodos alternativos para inserir entidades: insertOrMergeEntity e insertOrReplaceEntity. Para usar esses métodos, crie uma nova Entidade e passe-a como um parâmetro para qualquer método. Cada método insere a entidade se ela não existir. Se a entidade já existir, insertOrMergeEntity atualizará os valores de propriedade se as propriedades já existirem e adicionará novas propriedades se elas não existirem, enquanto insertOrReplaceEntity substituirá completamente uma entidade existente. O exemplo a seguir mostra como usar insertOrMergeEntity. Se a entidade com PartitionKey "tasksSeattle" e RowKey "1" ainda não existir, essa entidade será inserida. No entanto, se já existir (conforme mostrado no exemplo anterior), a DueDate propriedade será atualizada e a Status propriedade será adicionada. As propriedades Description e Location também são atualizadas, mas com valores que efetivamente as deixam inalteradas. Se essas duas últimas propriedades não tiverem sido adicionadas conforme mostrado no exemplo, mas existirem na entidade de destino, seus valores existentes permanecerão inalterados.

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 />";
}

Recuperar uma única entidade

O método TableRestProxy->getEntity permite que você recupere uma única entidade consultando seu PartitionKey e RowKey. No exemplo aqui, a chave tasksSeattle de partição e a chave 1 de linha são passadas para o método 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();

Recuperar todas as entidades em uma partição

Consultas de entidade são construídas usando filtros. Para obter mais informações, consulte Consultando tabelas e entidades. Para recuperar todas as entidades na partição, use o filtro PartitionKey eq partition_name. O exemplo a seguir mostra como recuperar todas as entidades na partição tasksSeattle passando um filtro para o método 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 />";
}

Recuperar um subconjunto de entidades em uma partição

O mesmo padrão usado no exemplo anterior pode ser usado para recuperar qualquer subconjunto de entidades em uma partição. O filtro usado determina o subconjunto de entidades que você recupera. Para obter mais informações, consulte Consultando tabelas e entidades. O exemplo a seguir mostra como usar um filtro para recuperar todas as entidades com uma data específica Location e DueDate menor que uma especificada.

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 />";
}

Recuperar um subconjunto de propriedades da entidade

Uma consulta pode recuperar um subconjunto de propriedades da entidade. Essa técnica, chamada projeção, reduz a largura de banda e pode melhorar o desempenho da consulta, principalmente para grandes entidades. Para especificar uma propriedade a ser recuperada, passe o nome da propriedade para o Query->addSelectField método . Você pode chamar esse método várias vezes para adicionar mais propriedades. Depois de executar TableRestProxy->queryEntities, as entidades retornadas terão apenas as propriedades selecionadas. Se você quiser retornar um subconjunto de entidades Table, use um filtro, conforme mostrado nas consultas anteriores.

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 />";
}

Atualizar uma entidade

Você pode atualizar uma entidade existente usando os métodos Entity->setProperty e Entity->addProperty na entidade e, em seguida, chamando TableRestProxy->updateEntity. O exemplo a seguir recupera uma entidade, modifica uma propriedade, remove outra propriedade e adiciona uma nova propriedade. Você pode remover uma propriedade definindo seu valor como nulo.

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 />";
}

Excluir uma entidade

Para excluir uma entidade, passe o nome da tabela e a PartitionKey e RowKey da entidade para o método 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 />";
}

Para verificações de simultaneidade, você pode definir o Etag para uma entidade a ser excluída, usando o métodoDeleteEntityOptions->setEtag e passando o objeto DeleteEntityOptions para deleteEntity como um quarto parâmetro.

Operações de tabela em lote

O método TableRestProxy->batch permite que você execute várias operações em uma única solicitação. O padrão aqui envolve a adição de operações para o objeto BatchRequest e, em seguida, passa o objeto BatchRequest para o método TableRestProxy->batch. Para adicionar uma operação a um objeto BatchRequest , você pode chamar várias vezes para qualquer um dos seguintes métodos:

	Descrição
addInsertEntity	Adiciona uma operação insertEntity
addUpdateEntity	Adiciona uma operação updateEntity
addMergeEntity	Adiciona uma operação mergeEntity
addInsertOrReplaceEntity	Adiciona uma operação insertOrReplaceEntity
addInsertOrMergeEntity	Adiciona uma operação insertOrMergeEntity
addDeleteEntity	Adiciona uma operação deleteEntity

O exemplo a seguir mostra como executar as operações insertEntity e deleteEntity em uma única solicitação.

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 />";
}

Para obter mais informações sobre operações de Tabela de envio em lote, confira Executando transações do grupo de entidade.

Excluir uma tabela

Finalmente, para excluir uma tabela, passe o nome da tabela para o método 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 />";
}

Conteúdo relacionado

• O Gerenciador de Armazenamento do Microsoft Azure é um aplicativo autônomo e gratuito da Microsoft que possibilita o trabalho visual com os dados do Armazenamento do Azure no Windows, MacOS e Linux.
• Central de Desenvolvimento do PHP.