Så här använder du Azure Storage Table-tjänsten eller Azure Cosmos DB for Table från PHP

Artikel
02/07/2024

GÄLLER FÖR: Tabell

Varning

Det här projektet är i communityns supportfas i livscykeln. Så småningom dras alla associerade klientbibliotek tillbaka permanent. Mer information om pensionering och alternativ till att använda det här projektet finns i Meddelande om pensionering: Azure Storage PHP-klientbibliotek.

Tips

Innehållet i den här artikeln gäller för Azure Table Storage och Azure Cosmos DB for Table. API:et för tabell är ett premiumerbjudande för tabelllagring som erbjuder dataflödesoptimerade tabeller, global distribution och automatiska sekundära index.

Den här artikeln visar hur du skapar tabeller, lagrar dina data och utför CRUD-åtgärder på data. Välj antingen Azure Table-tjänsten eller Azure Cosmos DB för Table. Exemplen är skrivna i PHP och använder PHP-klientbiblioteket för Azure Storage Table. Guiden innehåller scenarier som beskriver hur du skapar och tar bort en tabell och hur du infogar, tar bort och kör frågor mot entiteter i en tabell.

Skapa Ett Azure-tjänstkonto

Du kan arbeta med tabeller med hjälp av Azure Table Storage eller Azure Cosmos DB. Mer information om skillnaderna mellan tabellerbjudanden i dessa två tjänster finns i API:et för tabellöversikt. Du måste skapa ett konto för den tjänst som du ska använda. Följande avsnitt visar hur du skapar både Azure Table Storage och Azure Cosmos DB-kontot, men du kan bara använda en av dem.

Azure Table Storage

Det enklaste sättet att skapa ett Azure Storage-konto är att använda Azure Portal. Läs mer i Skapa ett lagringskonto.

Du kan även skapa ett Azure-lagringskonto med hjälp av Azure PowerShell eller Azure CLI.

Om du föredrar att inte skapa ett lagringskonto just nu kan du också använda Azure Storage-emulatorn för att köra och testa koden i en lokal miljö. Mer information finns i Använda Azure Storage-emulatorn för utveckling och testning.

Azure Cosmos DB för tabell

Anvisningar om hur du skapar ett Azure Cosmos DB för tabellkonto finns i Skapa ett databaskonto.

Skapa ett PHP-program

Det enda kravet för att skapa ett PHP-program för åtkomst till Storage Table-tjänsten eller Azure Cosmos DB for Table är att referera till klasser i azure-storage-table SDK för PHP inifrån din kod. Du kan använda valfritt utvecklingsverktyg för att skapa programmet, inklusive Anteckningar.

I den här guiden använder du Azure Table Storage eller Azure Cosmos DB for Table-funktioner som kan anropas inifrån ett PHP-program. Programmet kan köras lokalt eller i kod som körs inom en Azure-webbroll, arbetsroll eller webbplats.

Hämta klientbiblioteket

Skapa en fil med namnet composer.json i roten av projektet och lägg till följande kod i filen:
```
{
"require": {
 "microsoft/azure-storage-table": "*"
}
}
```
Ladda ned composer.phar till roten.
Öppna en kommandotolk och kör följande kommando i projektroten:
```
php composer.phar install
```
Du kan också gå till PHP-klientbiblioteket för Azure Storage Table på GitHub och klona källkoden.

Lägga till nödvändiga referenser

För att kunna använda Storage Table-tjänsten eller Azure Cosmos DB-API:er måste du:

Referera till autoloader-filen med hjälp av instruktionen require_once och
Referera till de klasser som du använder.

Följande exempel beskriver hur du lägger till autoloader-filen och refererar till klassen TableRestProxy.

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

I exemplen här visas alltid -instruktionen require_once , men endast de klasser som krävs för att exemplet ska köras refereras.

Lägg till anslutningssträng

Du kan antingen ansluta till Azure Storage-kontot eller Azure Cosmos DB för tabellkontot. Hämta anslutningssträng baserat på vilken typ av konto du använder.

Lägga till en anslutning till Storage Table-tjänsten

För att instantiera en Storage Table-tjänstklient behöver du en giltig anslutningssträng. Anslutningssträngar för Storage Table-tjänsten har följande format:

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

Lägga till en Storage Emulator-anslutning

Så här kommer du åt emulatorlagring:

UseDevelopmentStorage = true

Lägga till en Azure Cosmos DB-anslutning

För att instantiera en Azure Cosmos DB Table-klient behöver du en giltig anslutningssträng. Anslutningssträngar för Azure Cosmos DB har följande format:

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

När du skapar en Azure Table Storage-klient eller Azure Cosmos DB-klient måste du använda klassen TableRestProxy. Du kan:

Ange anslutningssträngen direkt i klassen eller
Använd CloudConfigurationManager (CCM) för att kontrollera flera externa källor för anslutningssträng:
- Som standard finns stöd för en extern källa – miljövariabler.
- Du kan lägga till nya källor genom att utöka ConnectionStringSource-klassen.

I exemplen som beskrivs här anges anslutningssträngen direkt.

require_once 'vendor/autoload.php';

use MicrosoftAzure\Storage\Table\TableRestProxy;

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

Skapa en tabell

Med TableRestProxy-objektet kan du skapa en tabell med metoden createTable. När du skapar en tabell kan du ange ett timeout-värde för Table Storage-tjänsten. Mer information om tidsgränsen för Table Service finns i Ange tidsgränser för table service-åtgärder.

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
}

Mer information om begränsningar för tabellnamn finns i Understanding the Table Service Data Model (Så här fungerar datamodellen för Table Storage).

Lägga till en entitet i en tabell

Om du vill lägga till en entitet i en tabell skapar du ett nytt entitetsobjekt och skickar det till TableRestProxy-insertEntity>. När du skapar en entitet måste du ange en PartitionKey och RowKey. Dessa entiteter är unika identifierare för en entitet och är värden som kan efterfrågas snabbare än andra entitetsegenskaper. PartitionKey används för att automatiskt distribuera tabellens entiteter mellan flera Storage-noder. Entiteter med samma PartitionKey lagras på samma nod. Åtgärder på flera entiteter som lagras på samma nod fungerar bättre än på entiteter som lagras på olika noder. RowKey är en entitets unika ID i en partition.

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

Information om tabellegenskaper och tabelltyper finns i Understanding the Table Service Data Model (Så här fungerar datamodellen för Table Storage).

Klassen TableRestProxy har två alternativa metoder som kan användas för att infoga entiteter: insertOrMergeEntity och insertOrReplaceEntity. Om du vill använda dessa metoder skapar du en ny entitet och skickar den som en parameter till någon av metoderna. Varje metod infogar entiteten om den inte finns. Om entiteten redan finns uppdaterar insertOrMergeEntity egenskapsvärden om egenskaperna redan finns och lägger till nya egenskaper om de inte finns, medan insertOrReplaceEntity helt ersätter en befintlig entitet. I följande exempel visas hur du använder insertOrMergeEntity. Om entiteten med PartitionKey "tasksSeattle" och RowKey "1" inte redan finns infogas den entiteten. Men om den redan finns (som i föregående exempel) DueDate uppdateras egenskapen och egenskapen Status läggs till. Egenskaperna Description och Location uppdateras också, men med värden som inte ändrar dem. Om dessa två senare egenskaper inte lades till som i exemplet, men fanns på målentiteten, skulle deras befintliga värden förbli oförändrade.

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

Hämta en enda entitet

Med metoden TableRestProxy-getEntity> kan du hämta en enda entitet genom att fråga efter dess PartitionKey och RowKey. I exemplet här skickas partitionsnyckeln tasksSeattle och radnyckeln 1 till metoden 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();

Hämta alla entiteter i en partition

Entitetsfrågor skapas med hjälp av filter. Mer information finns i Köra frågor mot tabeller och entiteter. Om du vill hämta alla entiteter i partitionen använder du filtret PartitionKey eq partition_name. I följande exempel beskriver vi hur du hämtar alla entiteter i partitionen tasksSeattle genom att ange ett filter i metoden 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 />";
}

Hämta en deluppsättning entiteter i en partition

Samma mönster som används i föregående exempel kan användas för att hämta en deluppsättning entiteter i en partition. Filtret som du använder avgör delmängden av entiteter som du hämtar. Mer information finns i Köra frågor mot tabeller och entiteter. I följande exempel visas hur du använder ett filter för att hämta alla entiteter med ett specifikt Location och mindre DueDate än ett angivet 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 />";
}

Hämta en deluppsättning entitetsegenskaper

En fråga kan hämta en deluppsättning entitetsegenskaper. Den här tekniken, som kallas projektion, minskar bandbredden och kan förbättra frågeprestanda, särskilt för stora entiteter. Om du vill ange en egenskap som ska hämtas skickar du namnet på egenskapen till Query->addSelectField -metoden. Du kan anropa den här metoden flera gånger om du vill lägga till fler egenskaper. När du har kört TableRestProxy->queryEntitieshar de returnerade entiteterna bara de valda egenskaperna. Om du vill returnera en delmängd av Tabellentiteter använder du ett filter som visas i föregående frågor.

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

Uppdatera en entitet

Du kan uppdatera en befintlig entitet med hjälp av metoderna Entity-setProperty> och Entity-addProperty> på entiteten och sedan anropa TableRestProxy-updateEntity>. Koden i följande exempel hämtar en entitet, ändrar en egenskap, tar bort en annan egenskap och lägger till en ny egenskap. Du kan ta bort en egenskap genom att ange värdet 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 />";
}

Ta bort en entitet

Om du vill ta bort en entitet skickar du tabellnamnet och entitetens PartitionKey och RowKey till metoden 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 />";
}

För samtidighetskontroller kan du ange Etag för en entitet som ska tas bort med hjälp av metoden DeleteEntityOptions-setEtag> och skicka objektet DeleteEntityOptions till deleteEntity som en fjärde parameter.

Tabellåtgärder i batchar

Med metoden TableRestProxy-batch> kan du köra flera åtgärder i en enda begäran. Mönstret här omfattar att lägga till åtgärder i BatchRequest-objektet och sedan skicka BatchRequest-objektet till metoden TableRestProxy-batch>. Du lägger till en åtgärd i ett BatchRequest-objekt genom att anropa någon av följande metoder flera gånger:

	Description
`addInsertEntity`	Lägger till en insertEntity-åtgärd
`addUpdateEntity`	Lägger till en updateEntity-åtgärd
`addMergeEntity`	Lägger till en mergeEntity-åtgärd
`addInsertOrReplaceEntity`	Lägger till en insertOrReplaceEntity-åtgärd
`addInsertOrMergeEntity`	Lägger till en insertOrMergeEntity-åtgärd
`addDeleteEntity`	Lägger till en deleteEntity-åtgärd

Följande exempel visar hur du kör insertEntity- och deleteEntity-åtgärder i en enda begäran.

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

Mer information om batchbearbetning av tabellåtgärder finns i Utföra entitetsgrupptransaktioner.

Ta bort en tabell

Om du vill ta bort en tabell skickar du slutligen tabellnamnet till metoden 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 Storage Explorer är en kostnadsfri, fristående app från Microsoft som gör det möjligt att arbeta visuellt med Azure Storage-data i Windows, macOS och Linux.
PHP Developer Center.

Dela via

Så här använder du Azure Storage Table-tjänsten eller Azure Cosmos DB for Table från PHP

Skapa Ett Azure-tjänstkonto

Azure Table Storage

Azure Cosmos DB för tabell

Skapa ett PHP-program

Hämta klientbiblioteket

Lägga till nödvändiga referenser

Lägg till anslutningssträng

Lägga till en anslutning till Storage Table-tjänsten

Lägga till en Storage Emulator-anslutning

Lägga till en Azure Cosmos DB-anslutning

Skapa en tabell

Lägga till en entitet i en tabell

Hämta en enda entitet

Hämta alla entiteter i en partition

Hämta en deluppsättning entiteter i en partition

Hämta en deluppsättning entitetsegenskaper

Uppdatera en entitet

Ta bort en entitet

Tabellåtgärder i batchar

Ta bort en tabell

Ytterligare resurser

Dela via

Så här använder du Azure Storage Table-tjänsten eller Azure Cosmos DB for Table från PHP

Skapa Ett Azure-tjänstkonto

Azure Table Storage

Azure Cosmos DB för tabell

Skapa ett PHP-program

Hämta klientbiblioteket

Lägga till nödvändiga referenser

Lägg till anslutningssträng

Lägga till en anslutning till Storage Table-tjänsten

Lägga till en Storage Emulator-anslutning

Lägga till en Azure Cosmos DB-anslutning

Skapa en tabell

Lägga till en entitet i en tabell

Hämta en enda entitet

Hämta alla entiteter i en partition

Hämta en deluppsättning entiteter i en partition

Hämta en deluppsättning entitetsegenskaper

Uppdatera en entitet

Ta bort en entitet

Tabellåtgärder i batchar

Ta bort en tabell

Relaterat innehåll

Ytterligare resurser