Az Azure Storage Table szolgáltatás vagy az Azure Cosmos DB for Table használata PHP-ből

A KÖVETKEZŐRE VONATKOZIK: Tábla

Figyelmeztetés

Ez a projekt a közösség életciklusának támogatási szakaszában van. Végül az összes társított ügyfélkódtár véglegesen ki lesz vonva. A projekt kivezetésével és alternatíváival kapcsolatos további információkért lásd : Kivonási értesítés: Azure Storage PHP-ügyfélkódtárak.

Tipp

A cikk tartalma az Azure Table Storage-ra és az Azure Cosmos DB for Tablere vonatkozik. A Table API egy prémium szintű ajánlat a table storage számára, amely átviteli sebességre optimalizált táblákat, globális elosztást és automatikus másodlagos indexeket kínál.

Ez a cikk bemutatja, hogyan hozhat létre táblákat, tárolhatja az adatokat, és hogyan hajthat végre CRUD-műveleteket az adatokon. Válassza ki az Azure Table szolgáltatást vagy az Azure Cosmos DB for Table szolgáltatást. A kódminták PHP nyelven íródtak, és az Azure Storage Table PHP-hoz készült ügyféloldali kódtárát használják. Az ismertetett forgatókönyvek a táblák létrehozásával és törlésével, valamint a táblaentitások beszúrásával, törlésével és lekérdezésével foglalkoznak.

Azure-szolgáltatásfiók létrehozása

A táblákkal az Azure Table Storage vagy az Azure Cosmos DB használatával dolgozhat. Ha többet szeretne megtudni a táblaajánlatok közötti különbségekről ebben a két szolgáltatásban, tekintse meg az API for Table áttekintését. Létre kell hoznia egy fiókot a használni kívánt szolgáltatáshoz. Az alábbi szakaszok bemutatják, hogyan hozható létre az Azure Table Storage és az Azure Cosmos DB-fiók is, de csak az egyiket használhatja.

Azure Table Storage

Az Azure Storage-fiók létrehozásának legegyszerűbb módja a Azure Portal használata. További tudnivalókért lásd: Create a storage account (Tárfiók létrehozása).

Ezenkívül az Azure PowerShell vagy az Azure CLI használatával is létrehozhat egy Azure-tárfiókot.

Ha jelenleg nem szeretne tárfiókot létrehozni, az Azure Storage Emulator használatával helyi környezetben is futtathatja és tesztelheti a kódot. További információ: Az Azure Storage Emulator használata fejlesztéshez és teszteléshez.

Azure Cosmos DB for Table

Az Azure Cosmos DB for Table-fiók létrehozásával kapcsolatos utasításokért lásd: Adatbázisfiók létrehozása.

PHP-alkalmazás létrehozása

A Storage Table szolgáltatás vagy az Azure Cosmos DB for Table eléréséhez egyetlen követelmény egy PHP-alkalmazás létrehozása, ha a kódon belül hivatkozik a PHP-hoz készült azure-storage-table SDK osztályaira. Az alkalmazás létrehozásához bármilyen fejlesztői eszközt (pl. Jegyzettömböt) használhat.

Ebben az útmutatóban az Azure Table Storage vagy az Azure Cosmos DB for Table olyan funkcióit használja, amelyek egy PHP-alkalmazásból hívhatók meg. Az alkalmazás helyileg vagy egy Azure-beli webes szerepkörön, feldolgozói szerepkörön vagy webhelyen futó kódban is futtatható.

Az ügyfélkönyvtár lekérése

1. Hozzon létre egy composer.json nevű fájlt a projekt gyökérkönyvtárában, és adja hozzá az alábbi kódot:

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

2. Töltse le a composer.phar fájlt a gyökérkönyvtárba.

3. Nyissa meg a parancssort, és hajtsa végre az alábbi parancsot a projekt gyökérkönyvtárában:

   php composer.phar install
   

   Másik megoldásként navigáljon az Azure Storage Table PHP ügyféloldali kódtárához a GitHubon, és klónozza a forráskódot.

Szükséges referenciák hozzáadása

A Storage Table szolgáltatás vagy az Azure Cosmos DB API-k használatához a következőket kell tennie:

• Hivatkozzon az automatikus betöltő fájlra a require_once utasítás használatával, és
• hivatkozzon bármely felhasznált osztályra.

A következő példa bemutatja, hogyan használható az automatikus betöltő fájl és hogyan lehet a TableRestProxy osztályra hivatkozni.

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

Az itt látható példákban az require_once utasítás mindig megjelenik, de csak a végrehajtáshoz szükséges osztályokra hivatkozunk.

A kapcsolati karakterlánc hozzáadása

Csatlakozhat az Azure Storage-fiókhoz vagy az Azure Cosmos DB for Table-fiókhoz. Kérje le a kapcsolati karakterlánc a használt fiók típusa alapján.

Storage Table szolgáltatási kapcsolat hozzáadása

Storage Table szolgáltatási ügyfél példányosításához először is rendelkeznie kell egy érvényes kapcsolati sztringgel. A Storage szolgáltatás kapcsolati sztringjének formátuma:

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

Storage Emulator-kapcsolat hozzáadása

Az emulátor tárolójának elérése:

UseDevelopmentStorage = true

Azure Cosmos DB-kapcsolat hozzáadása

Azure Cosmos DB Table-ügyfél példányosításához először is rendelkeznie kell egy érvényes kapcsolati sztringgel. Az Azure Cosmos DB kapcsolati sztringjének formátuma:

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

Azure Table Service-ügyfél vagy Azure Cosmos DB-ügyfél létrehozásához a TableRestProxy osztályt kell használnia. A következőket teheti:

• A kapcsolati sztringet továbbíthatja közvetlenül, vagy
• A CloudConfigurationManager (CCM) használatával ellenőrizze a kapcsolati karakterlánc több külső forrását:
  • Alapértelmezés szerint csak egy külső forrást támogat: a környezeti változókat.
  • Új forrásokat a ConnectionStringSource osztály kiterjesztésével adhat hozzá.

Az itt ismertetett példák esetében a kapcsolati sztringet közvetlenül továbbítjuk.

require_once 'vendor/autoload.php';

use MicrosoftAzure\Storage\Table\TableRestProxy;

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

Tábla létrehozása

A TableRestProxy objektum lehetővé teszi egy tábla létrehozását a createTable metódussal. Tábla létrehozásakor beállíthatja a Table Service időkorlátját. A Table Service időtúllépésével kapcsolatos további információkért lásd: Időtúllépések beállítása a Table Service-műveletekhez.

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
}

További információt a táblák nevére vonatkozó korlátozásokról a Table Service adatmodelljét ismertető témakörben talál.

Entitás hozzáadása a táblához

Ha entitást szeretne hozzáadni egy táblához, hozzon létre egy új Entity objektumot, és adja át a TableRestProxy-insertEntity> elemnek. Entitás létrehozásakor meg kell adnia egy és RowKeyértéketPartitionKey. Ezek az entitások egy entitás egyedi azonosítói, és olyan értékek, amelyek gyorsabban lekérdezhetők, mint más entitástulajdonságok. A rendszer a PartitionKey használatával automatikusan elosztja a tábla entitásait számos tárcsomópont között. Az ugyanazzal a PartitionKey tulajdonsággal rendelkező entitások tárolása ugyanazon a csomóponton történik. Az ugyanazon a csomóponton tárolt több entitáson végzett műveletek jobban teljesítenek, mint a különböző csomópontokon tárolt entitásokon. A RowKey az entitás egyedi azonosítója egy partíción belül.

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

További információt a táblatulajdonságokról és -típusokról a Table Service adatmodelljét ismertető témakörben talál.

A TableRestProxy osztály két alternatív metódust kínál az entitások beszúrásához: az insertOrMergeEntity és az insertOrReplaceEntity metódust. A két metódus használatához hozzon létre egy új entitást, és továbbítsa azt valamelyik metódusnak paraméterként. Minden metódus beszúrja az entitást, ha nem létezik. Ha az entitás már létezik, az insertOrMergeEntity frissíti a tulajdonságértékeket, ha a tulajdonságok már léteznek, és új tulajdonságokat ad hozzá, ha nem léteznek, míg az insertOrReplaceEntity teljes mértékben lecserél egy meglévő entitást. Az alábbi példa a használatát insertOrMergeEntitymutatja be. Ha a "tasksSeattle" és RowKey az "1" entitás PartitionKey még nem létezik, akkor az entitás be lesz szúrva. Ha azonban már létezik (az előző példában látható módon), a DueDate tulajdonság frissül, és hozzáadja a Status tulajdonságot. A Description és Location tulajdonságok is frissülnek, de olyan értékekkel, amelyek révén lényegében nem változnak. Ha ez utóbbi két tulajdonság nem lett hozzáadva a példában látható módon, de léteznek a célentitáson, a meglévő értékek változatlanok maradnak.

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

Egyetlen entitás lekérdezése

A TableRestProxy-getEntity> metódus lehetővé teszi egyetlen entitás lekérését a és RowKeya lekérdezésévelPartitionKey. Az itt látható példában a partíciókulcs tasksSeattle és a sorkulcs 1 a getEntity metódusnak lesz átadva.

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

Egy partíció összes entitásának lekérése

Az entitás-lekérdezések szűrők használatával jönnek létre. További információ: Táblák és entitások lekérdezése. A partíció összes entitásának lekéréséhez használja a szűrőt PartitionKey eq partition_name. Az alábbi példa bemutatja, hogyan kérheti le a tasksSeattle partíció minden entitását úgy, hogy egy szűrőt továbbít a queryEntities metódusnak.

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

Entitások egy részének lekérése egy partíción belül

Az előző példában használt minta felhasználható entitások bármilyen részhalmazának lekérésére egy partíción belül. A használt szűrő határozza meg a lekért entitások részhalmazát. További információ: Táblák és entitások lekérdezése. Az alábbi példa bemutatja, hogyan lehet szűrővel lekérni a megadott Location dátumnál kisebb dátumú entitásokat 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 />";
}

Az entitástulajdonságok egy részének lekérése

Egy lekérdezéssel lekérhető az entitástulajdonságok egy része. Ez a leképezésnek hívott technika csökkenti a sávszélesség felhasználását, és javíthatja a lekérdezési teljesítményt, főleg a nagy entitások esetén. A beolvasandó tulajdonság megadásához adja meg a tulajdonság nevét a Query->addSelectField metódusnak. Ezt a metódust többször is meghívhatja, ha több tulajdonságot szeretne hozzáadni. A végrehajtás TableRestProxy->queryEntitiesután a visszaadott entitások csak a kiválasztott tulajdonságokkal rendelkeznek. Ha a Table entitások egy részhalmazát szeretné visszaadni, használjon szűrőt az előző lekérdezésekben látható módon.

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

Entitás frissítése

Egy meglévő entitást frissíthet az entitás Entity-setProperty> és Entity-addProperty> metódusával, majd meghívhatja a TableRestProxy-updateEntity> metódust. A következő példa visszaad egy entitást, módosít egy tulajdonságot, eltávolít egy másik tulajdonságot, és hozzáad egy újat. A tulajdonságot úgy távolíthatja el, hogy null értékűre állítja.

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

Entitás törlése

Egy entitás törléséhez adja meg a tábla nevét, valamint az entitás PartitionKey nevét és RowKey a TableRestProxy-deleteEntity> metódust .

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

Egyidejűségi ellenőrzések esetén beállíthatja, hogy egy entitás Etagje törölhető legyen a DeleteEntityOptions-setEtag> metódussal, és a DeleteEntityOptions objektumot a deleteEntity paraméterre továbbítja negyedik paraméterként.

Kötegelt táblaműveletek

A TableRestProxy-batch> metódussal több műveletet is végrehajthat egyetlen kérelemben. Ebben a mintában műveleteket kell hozzáadni a BatchRequest objektumhoz, majd átadni a BatchRequest objektumot a TableRestProxy-batch> metódusnak. Ha egy műveletet szeretne hozzáadni a BatchRequest objektumhoz, az alábbi metódusok bármelyikét többször is meghívhatja:

	Description
addInsertEntity	Beszúrási művelet hozzáadása
addUpdateEntity	UpdateEntity művelet hozzáadása
addMergeEntity	MergeEntity művelet hozzáadása
addInsertOrReplaceEntity	InsertOrReplaceEntity művelet hozzáadása
addInsertOrMergeEntity	InsertOrMergeEntity művelet hozzáadása
addDeleteEntity	DeleteEntity művelet hozzáadása

A következő példa az insertEntity és a deleteEntity művelet egy kérésben történő végrehajtásának módját mutatja be.

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

További információk a táblaműveletek kötegeléséről: Entitáscsoport-tranzakciók végrehajtása.

Tábla törlése

Végül egy tábla törléséhez adja át a tábla nevét a TableRestProxy-deleteTable> metódusnak.

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

Kapcsolódó tartalom

• A Microsoft Azure Storage Explorer egy ingyenes, önálló alkalmazás, amelynek segítségével vizuálisan dolgozhat Azure Storage-adatokkal Windows, macOS és Linux rendszereken.
• PHP fejlesztői központ.