Jak používat službu Azure Storage Table service nebo Azure Cosmos DB for Table z PHP

PLATÍ PRO: Tabulka

Upozornění

Tento projekt je ve fázi podpory komunity životního cyklu. Nakonec budou všechny přidružené klientské knihovny trvale vyřazeny. Další informace o vyřazení z provozu a alternativách k použití tohoto projektu najdete v tématu Oznámení o vyřazení z provozu: Klientské knihovny PHP služby Azure Storage.

Tip

Obsah v tomto článku platí pro Azure Table Storage a Azure Cosmos DB for Table. Rozhraní API pro tabulky je prémiová nabídka pro table Storage, která nabízí tabulky optimalizované pro propustnost, globální distribuci a automatické sekundární indexy.

V tomto článku se dozvíte, jak vytvářet tabulky, ukládat data a provádět operace CRUD s daty. Zvolte službu Azure Table service nebo Azure Cosmos DB for Table. Ukázky jsou napsané v PHP a využívají klientskou knihovnu služby Azure Table Storage pro PHP. Popsané scénáře zahrnují vytvoření a odstranění tabulky a vkládání, odstraňování a dotazování entit v tabulce.

Vytvoření účtu služby Azure

S tabulkami můžete pracovat pomocí služby Azure Table Storage nebo Azure Cosmos DB. Další informace o rozdílech mezi nabídkami tabulek v těchto dvou službách najdete v přehledu rozhraní API pro tabulky. Musíte vytvořit účet pro službu, kterou budete používat. Následující části ukazují, jak vytvořit azure Table Storage i účet Azure Cosmos DB, ale můžete použít jenom jeden z nich.

Azure Table Storage

Nejjednodušší způsob, jak vytvořit účet úložiště Azure, je použít Azure Portal. Další informace najdete v tématu Vytvoření účtu úložiště.

Účet úložiště Azure můžete vytvořit také pomocí Azure PowerShellu nebo Azure CLI.

Pokud nechcete v tuto chvíli vytvořit účet úložiště, můžete také použít Emulátor služby Azure Storage ke spuštění a testování kódu v místním prostředí. Další informace najdete v tématu Použití emulátoru služby Azure Storage pro vývoj a testování.

Azure Cosmos DB for Table

Pokyny k vytvoření účtu Služby Azure Cosmos DB for Table najdete v tématu Vytvoření databázového účtu.

Vytvoření aplikace PHP

Jediným požadavkem na vytvoření aplikace PHP pro přístup ke službě Storage Table nebo Službě Azure Cosmos DB for Table je odkazování na třídy v sadě SDK azure-storage-table pro PHP z vašeho kódu. K vytvoření aplikace můžete použít jakékoli vývojové nástroje, včetně Poznámkového bloku.

V této příručce použijete funkce Azure Table Storage nebo Azure Cosmos DB pro tabulky, které je možné volat z aplikace PHP. Aplikace může běžet místně nebo v kódu spuštěném v rámci webové role Azure, role pracovního procesu nebo webu.

Získání klientské knihovny

1. V kořenovém adresáři vašeho projektu vytvořte soubor composer.json a přidejte do něj následující kód:

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

2. Do kořenového adresáře stáhněte soubor composer.phar.

3. Otevřete příkazový řádek a spusťte následující příkaz v kořenovém adresáři vašeho projektu:

   php composer.phar install
   

   Případně můžete přejít do úložiště klientské knihovny služby Azure Table Storage pro PHP na GitHubu a zkopírovat si zdrojový kód.

Přidání požadovaných odkazů

Pokud chcete používat službu Table Storage nebo rozhraní API služby Azure Cosmos DB, musíte:

• Přidat odkaz na soubor automatického načítání pomocí příkazu require_once.
• Přidat odkazy na všechny třídy, které používáte.

Následující příklad ukazuje vložení souboru automatického načítání a odkazu na třídu TableRestProxy.

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

V příkladech je příkaz require_once vždy zobrazen, ale odkazuje se pouze na třídy nezbytné pro provedení příkladu.

Přidání připojovací řetězec

Můžete se připojit k účtu úložiště Azure nebo k účtu Azure Cosmos DB for Table. Získejte připojovací řetězec na základě typu účtu, který používáte.

Přidání připojení ke službě Table Storage

Pokud chcete vytvořit instanci klienta služby Table Storage, musíte nejprve mít platný připojovací řetězec. Formát připojovacího řetězce služby Table Storage je následující:

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

Přidání připojení emulátoru úložiště

Získání přístupu k úložišti emulátoru:

UseDevelopmentStorage = true

Přidání připojení ke službě Azure Cosmos DB

Pokud chcete vytvořit instanci klienta Azure Cosmos DB, musíte nejprve mít platný připojovací řetězec. Formát připojovacího řetězce Azure Cosmos DB je následující:

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

Pokud chcete vytvořit klienta služby Azure Table Storage nebo Azure Cosmos DB, musíte použít třídu TableRestProxy. Můžete:

• Do ní předat připojovací řetězec přímo nebo
• Pomocí správce CloudConfigurationManager (CCM) zkontrolujte více externích zdrojů pro připojovací řetězec:
  • Ve výchozím nastavení podporuje jeden externí zdroj – proměnné prostředí.
  • Nové zdroje můžete přidat rozšířením třídy ConnectionStringSource.

Ve zde uvedených příkladech se připojovací řetězec předává přímo.

require_once 'vendor/autoload.php';

use MicrosoftAzure\Storage\Table\TableRestProxy;

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

Vytvoření tabulky

Objekt TableRestProxy umožňuje vytvořit tabulku pomocí metody createTable. Při vytváření tabulky můžete nastavit časový limit služby Table Storage. Další informace o vypršení časového limitu služby Table Service najdete v tématu Nastavení časových limitů pro operace služby 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
}

Další informace o omezeních a názvech tabulek najdete v tématu Vysvětlení datového modelu služby Table Storage.

Přidání entity do tabulky

Pokud chcete přidat entitu do tabulky, vytvořte nový objekt Entity a předejte ho do TableRestProxy-insertEntity>. Při vytváření entity je nutné zadat PartitionKey a RowKey. Tyto entity jsou jedinečnými identifikátory entity a jedná se o hodnoty, na které je možné dotazovat rychleji než jiné vlastnosti entity. Systém používá PartitionKey k automatické distribuci entit tabulky do mnoha uzlů úložiště. Entity se stejnou hodnotou PartitionKey se ukládají na stejném uzlu. Operace s více entitami uloženými na stejném uzlu fungují lépe než s entitami uloženými v různých uzlech. RowKey představuje jedinečné ID entity v rámci oddílu.

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

Další informace o typech a vlastnostech služby Table Storage najdete v tématu Vysvětlení datového modelu služby Table Storage.

Třída TableRestProxy nabízí dvě alternativní metody pro vkládání entit: insertOrMergeEntity a insertOrReplaceEntity. Pokud chcete tyto metody použít, vytvořte nový objekt Entity a předejte ho jako parametr do jedné z těchto metod. Každá metoda vloží entitu, pokud neexistuje. Pokud entita již existuje, insertOrMergeEntity aktualizuje hodnoty vlastností, pokud vlastnosti již existují, a přidá nové vlastnosti, pokud neexistují, zatímco insertOrReplaceEntity zcela nahradí existující entitu. Následující příklad ukazuje, jak používat insertOrMergeEntity. Pokud entita s PartitionKey "tasksSeattle" a RowKey "1" ještě neexistuje, pak se tato entita vloží. Pokud však již existuje (jak je znázorněno v předchozím příkladu DueDate ), vlastnost se aktualizuje a Status vlastnost se přidá. Vlastnosti Description a Location se také aktualizují, ale s použitím hodnot, které je prakticky ponechají beze změny. Pokud by se tyto poslední dvě vlastnosti nepřidaly, jak je znázorněno v příkladu, ale existovaly v cílové entitě, jejich stávající hodnoty by zůstaly beze změny.

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

Načtení jedné entity

Metoda TableRestProxy-getEntity> umožňuje načíst jednu entitu dotazováním na její PartitionKey a RowKey. V tomto příkladu jsou klíč tasksSeattle oddílu a klíč 1 řádku předány metodě 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();

Načtení všech entit v oddílu

Dotazy na entity se konstruují pomocí filtrů. Další informace najdete v tématu Dotazování tabulek a entit. Pokud chcete načíst všechny entity v oddílu, použijte filtr PartitionKey eq partition_name. Následující příklad ukazuje načtení všech entit v oddílu tasksSeattle předáním filtru do metody 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 />";
}

Načtení podmnožiny entit v oddílu

Stejným způsobem, jako se použil v předchozím příkladu, je možné načíst jakoukoli podmnožinu entit v oddílu. Použitý filtr určuje podmnožinu entit, které načtete. Další informace najdete v tématu Dotazování tabulek a entit. Následující příklad ukazuje, jak pomocí filtru načíst všechny entity s konkrétním Location datem DueDate a kratším než zadané datum.

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

Načtení podmnožiny vlastností entity

Dotaz může načíst podmnožinu vlastností entity. Tato technika, označovaná jako projekce, snižuje šířku pásma a může zlepšit výkon dotazů, zejména u velkých entit. Chcete-li zadat vlastnost, která se má načíst, předejte název vlastnosti metodě Query->addSelectField . Tuto metodu můžete zavolat vícekrát a přidat další vlastnosti. Po spuštění TableRestProxy->queryEntitiesbudou mít vrácené entity pouze vybrané vlastnosti. Pokud chcete vrátit podmnožinu entit tabulky, použijte filtr, jak je znázorněno v předchozích dotazech.

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

Aktualizace entity

Existující entitu můžete aktualizovat pomocí metod Entity-setProperty> a Entity-addProperty> v entitě a poté voláním TableRestProxy-updateEntity>. Následující příklad načte entitu, upraví jednu vlastnost, odebere jinou vlastnost a přidá novou vlastnost. Vlastnost můžete odebrat nastavením její hodnoty na hodnotu 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 />";
}

Odstranění entity

Pokud chcete odstranit entitu, předejte název tabulky a entity PartitionKey a RowKey metodě 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 />";
}

Pro kontroly souběžnosti můžete nastavit Etag entity, která se má odstranit pomocí metody DeleteEntityOptions-setEtag> a předáním objektu DeleteEntityOptionsna deleteEntity jako čtvrtý parametr.

Dávkové operace s tabulkou

Metoda TableRestProxy-batch> umožňuje provádět více operací v jednom požadavku. Vzor zde zahrnuje přidání operací do objektu BatchRequest a následné předání objektu BatchRequestmetodě TableRestProxy-batch>. Pokud chcete do objektu BatchRequest přidat operaci, můžete několikrát zavolat jakoukoli z následujících metod:

	Description
addInsertEntity	Přidá operaci insertEntity.
addUpdateEntity	Přidá operaci updateEntity.
addMergeEntity	Přidá operaci mergeEntity.
addInsertOrReplaceEntity	Přidá operaci insertOrReplaceEntity.
addInsertOrMergeEntity	Přidá operaci insertOrMergeEntity.
addDeleteEntity	Přidá operaci deleteEntity.

Následující příklad ukazuje spuštění operací insertEntity a deleteEntity v rámci jednoho požadavku.

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

Další informace o dávkování operací s tabulkou najdete v tématu Provádění transakcí skupin entit.

Odstranění tabulky

Nakonec, chcete-li odstranit tabulku, předejte název tabulky TableRestProxy-deleteTable> metody.

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

Související obsah

• Microsoft Azure Storage Explorer je bezplatná samostatná aplikace od Microsoftu, která umožňuje vizuálně pracovat s daty Azure Storage ve Windows, macOS a Linuxu.
• Centrum pro vývojáře PHP