PHP から Azure Storage Table service API または Azure Cosmos DB for Table を使用する方法

適用対象: テーブル

警告

このプロジェクトは、ライフサイクルの コミュニティ サポート 段階にあります。 最終的に、関連付けられているすべてのクライアント ライブラリは完全に廃止されます。 このプロジェクトを使用するための廃止と代替方法の詳細については、「 廃止に関する通知: Azure Storage PHP クライアント ライブラリ」を参照してください。

ヒント

この記事の内容は、Azure Table Storage と Azure Cosmos DB for Table に適用されます。 Table 用 API は、スループット最適化テーブル、グローバル分散、自動セカンダリ インデックスを提供するテーブル ストレージ向けの Premium オファリングです。

この記事では、テーブルの作成、データの格納、データに対する CRUD 操作の実行を行う方法について説明します。 Azure Table service または Azure Cosmos DB for Table のいずれかを選択してください。 サンプルは PHP で記述されており、Azure Storage Table PHP クライアント ライブラリを使います。 紹介するシナリオは、テーブルの作成と削除、テーブルのエンティティの挿入、削除、および照会などです。

Azure サービス アカウントを作成する

Azure Table ストレージまたは Azure Cosmos DB を使用してテーブルを操作できます。 これら 2 つのサービスのテーブル サービスの違いについては、Table 用 API の概要に関するページを参照してください。 使用するサービスのアカウントを作成する必要があります。 以下のセクションでは、Azure Table ストレージと Azure Cosmos DB アカウントの両方を作成する方法について説明しますが、そのうちの 1 つのみを使用できます。

Azure Table Storage

Azure ストレージ アカウントを作成する最も簡単な方法は、Azure portal を利用することです。 詳細については、「 ストレージ アカウントの作成」を参照してください。

Azure PowerShell または Azure CLI を使って、Azure Storage アカウントを作成することもできます。

現時点でストレージ アカウントを作成しない場合は、Azure Storage エミュレーターを使って、ローカル環境でコードの実行とテストを行うこともできます。 詳細については、「開発とテストのための Azure のストレージ エミュレーター使用」を参照してください。

Azure Cosmos DB for Table

Azure Cosmos DB for Table アカウントの作成手順については、「データベース アカウントの作成」を参照してください。

PHP アプリケーションの作成

Storage Table service API または Azure Cosmos DB for Table にアクセスする PHP アプリケーションを作成するための唯一の要件は、コード内から azure-storage-table SDK for PHP のクラスを参照することです。 アプリケーションの作成には、メモ帳などの任意の開発ツールを使用できます。

このガイドでは、PHP アプリケーション内から呼び出すことができる Azure Table Storage または Azure Cosmos DB for Table 機能を使用します。 アプリケーションは、Azure Web ロール、worker ロール、または Web サイト内で実行されているローカルまたはコードで実行できます。

クライアント ライブラリを入手する

1. プロジェクトのルートに composer.json という名前のファイルを作成して、次のコードを追加します。

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

2. composer.phar をルートにダウンロードします。

3. コマンド プロンプトを開き、次のコマンドをプロジェクトのルートで実行します。

   php composer.phar install
   

   または、GitHub で Azure Storage Table PHP Client Library に移動し、ソース コードを複製します。

必要な参照を追加する

Storage Table service API または Azure Cosmos DB API を使うには、次のことが必要です。

• require_once ステートメントを使ってオートローダー ファイルを参照する
• 使うクラスを参照する

次の例では、オートローダー ファイルをインクルードし、TableRestProxy クラスを参照する方法を示します。

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

ここでの例では、 require_once ステートメントは常に表示されますが、例の実行に必要なクラスのみが参照されます。

接続文字列を追加する

Azure Storage アカウントまたは Azure Cosmos DB for Table アカウントのいずれかに接続できます。 使用しているアカウントの種類に基づいて接続文字列を取得します。

Storage Table service の接続を追加する

Storage Table service クライアントをインスタンス化するには、まず有効な接続文字列が必要です。 Storage Table service の接続文字列の形式は次のとおりです。

$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 Table service クライアントまたは Azure Cosmos DB クライアントを作成するには、TableRestProxy クラスを使う必要があります。 次のようにすることができます。

• 接続文字列を直接渡す
• CloudConfigurationManager (CCM) を使用して複数の外部ソースに対して接続文字列を確認する
  • 既定では 1 つの外部ソース (環境変数) のみサポートされています。
  • ConnectionStringSource クラスを拡張して新しいソースを追加できます。

ここで概説している例では、接続文字列が直接渡されます。

require_once 'vendor/autoload.php';

use MicrosoftAzure\Storage\Table\TableRestProxy;

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

テーブルを作成する

TableRestProxy オブジェクトの createTable メソッドを使用してテーブルを作成できます。 テーブルの作成時、Table service のタイムアウトを設定できます Table Service のタイムアウトの詳細については、「 Table Service 操作のタイムアウトの設定」を参照してください。

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
}

テーブル名の制限については、「Table サービス データ モデルについて」を参照してください。

エンティティをテーブルに追加する

エンティティをテーブルに追加するには、新しい Entity オブジェクトを作成し、TableRestProxy->insertEntity に渡します。 エンティティを作成するときは、 と RowKeyを指定するPartitionKey必要があります。 これらのエンティティはエンティティの一意の識別子であり、他のエンティティ プロパティよりも高速にクエリできる値です。 システムは PartitionKey を使って多くのストレージ ノードにテーブルのエンティティを自動的に配布します。 PartitionKey が同じエンティティは同じノードで格納されています 同じノードに格納されている複数のエンティティに対する操作は、異なるノードに格納されているエンティティよりも優れています。 RowKey は特定のパーティション内のエンティティの一意の ID です。

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

テーブルのプロパティと型については、「Table サービス データ モデルについて」を参照してください。

TableRestProxy クラスには、ほかにもエンティティを挿入する 2 つのメソッド、insertOrMergeEntity と insertOrReplaceEntity が用意されています。 これらのメソッドを使用するには、新しい Entity を作成し、いずれかのメソッドにパラメーターとして渡します。 エンティティが存在しない場合、各メソッドはエンティティを挿入します。 エンティティが既に存在する場合、 insertOrMergeEntity はプロパティが既に存在する場合はプロパティ値を更新し、存在しない場合は新しいプロパティを追加しますが、 insertOrReplaceEntity は既存のエンティティを完全に置き換えます。 次の例は、insertOrMergeEntity を使用する方法を示しています。 "tasksSeattle" と RowKey "1" のエンティティPartitionKeyがまだ存在しない場合は、そのエンティティが挿入されます。 ただし、(前の例に示すように) DueDate 既に存在する場合は、 プロパティが更新され Status 、 プロパティが追加されます。 Description プロパティと Location プロパティも更新されますが、値は実際には変更されないままになります。 これらの後者の 2 つのプロパティが例に示すように追加されていないが、ターゲット エンティティに存在していた場合、既存の値は変更されません。

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 を照会することで、1 つのエンティティを取得できます。 この例では、パーティション キーと行キー tasksSeattle1 が 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。 次の例では、フィルターを queryEntities メソッドに渡すことで、tasksSeattle パーティション内のすべてのエンティティを取得する方法を示しています。

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

パーティション内のエンティティのサブセットを取得する

前の例で示している同じパターンを使用してパーティション内のエンティティのサブセットを取得できます。 使用するフィルターによって、取得するエンティティのサブセットが決まります。 詳細については、「 テーブルとエンティティのクエリ」を参照してください。 次の例は、フィルターを使用して、指定した日付未満の特定 Location の DueDate エンティティをすべて取得する方法を示しています。

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すると、返されるエンティティには選択されたプロパティのみが含まれます。 Table エンティティのサブセットを返す場合は、前のクエリに示すようにフィルターを使用します。

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 を呼び出すことで更新できます。 次の例では、エンティティを取得してから、1 つのプロパティの変更、別のプロパティの削除、新しいプロパティの追加を行っています。 プロパティを削除するには、その値を 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 オブジェクトを 4 番目のパラメーターとして deleteEntity に渡します。

バッチ テーブル処理

TableRestProxy->batch メソッドを使用すると、1 つの要求で複数の処理を実行できます。 ここで示しているパターンでは、処理を BatchRequest オブジェクトに追加し、BatchRequest オブジェクトを TableRestProxy->batch メソッドに渡しています。 処理を BatchRequest オブジェクトに追加するには、次のいずれかのメソッドを複数回呼び出すことができます。

	説明
addInsertEntity	insertEntity 操作を追加します
addUpdateEntity	updateEntity 操作を追加します
addMergeEntity	mergeEntity 操作を追加します
addInsertOrReplaceEntity	insertOrReplaceEntity 操作を追加します
addInsertOrMergeEntity	insertOrMergeEntity 操作を追加します
addDeleteEntity	deleteEntity 操作を追加します

次の例では、1 つの要求で 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 />";
}

テーブル バッチ処理の詳細については、「エンティティ グループ トランザクションの実行」を参照してください。

テーブルを削除する

最後に、テーブルを削除するには、テーブル名を 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 ストレージ エクスプローラーは、Windows、macOS、Linux で Azure Storage のデータを視覚的に操作できる Microsoft 製の無料のスタンドアロン アプリです。
• PHP デベロッパー センター