Jak używać usługi Azure Storage Table Service lub usługi Azure Cosmos DB dla tabel w języku PHP

DOTYCZY: Tabela

Ostrzeżenie

Ten projekt znajduje się na etapie wsparcia społeczności w cyklu życia. Ostatecznie wszystkie skojarzone biblioteki klienckie zostaną trwale wycofane. Aby uzyskać więcej informacji na temat wycofywania i alternatyw dla korzystania z tego projektu, zobacz Powiadomienie o wycofaniu: Biblioteki klienta PHP usługi Azure Storage.

Porada

Zawartość tego artykułu dotyczy usług Azure Table Storage i Azure Cosmos DB dla tabel. Interfejs API dla tabel to oferta Premium dla magazynu tabel, która oferuje tabele zoptymalizowane pod kątem przepływności, dystrybucję globalną i automatyczne indeksy pomocnicze.

W tym artykule pokazano, jak tworzyć tabele, przechowywać dane i wykonywać operacje CRUD na danych. Wybierz usługę Azure Table Service lub usługę Azure Cosmos DB dla tabeli. Przykłady są napisane w języku PHP i korzystają z biblioteki klienta usługi Azure Table Storage dla języka PHP. Przedstawione scenariusze obejmują tworzenie i usuwanie tabel, wstawianie i usuwanie jednostek w tabeli oraz wykonywanie zapytań dotyczących jednostek.

Tworzenie konta usługi platformy Azure

Możesz pracować z tabelami przy użyciu usługi Azure Table Storage lub usługi Azure Cosmos DB. Aby dowiedzieć się więcej o różnicach między ofertami tabel w tych dwóch usługach, zobacz omówienie interfejsu API dla tabel. Musisz utworzyć konto dla usługi, której będziesz używać. W poniższych sekcjach pokazano, jak utworzyć zarówno usługę Azure Table Storage, jak i konto usługi Azure Cosmos DB, jednak możesz po prostu użyć jednego z nich.

Azure Table Storage

Najprostszym sposobem utworzenia konta usługi Azure Storage jest użycie Azure Portal. Więcej informacji można znaleźć w temacie Tworzenie konta magazynu.

Możesz utworzyć konto usługi Azure Storage przy użyciu programu Azure PowerShell lub interfejsu wiersza polecenia platformy Azure.

Jeśli w tej chwili nie chcesz tworzyć konta magazynu, możesz również użyć emulatora usługi Azure Storage do uruchomienia i przetestowania kodu w środowisku lokalnym. Aby uzyskać więcej informacji, zobacz Use the Azure Storage Emulator for development and testing (Używanie emulatora usługi Azure Storage do programowania i testowania).

Usługa Azure Cosmos DB dla tabeli

Aby uzyskać instrukcje dotyczące tworzenia konta usługi Azure Cosmos DB dla tabel, zobacz Tworzenie konta bazy danych.

Tworzenie aplikacji języka PHP

Jedynym wymaganiem do utworzenia aplikacji PHP w celu uzyskania dostępu do usługi Storage Table Service lub usługi Azure Cosmos DB dla tabeli jest odwołanie się do klas w zestawie SDK azure-storage-table dla języka PHP z poziomu kodu. Do utworzenia aplikacji możesz użyć dowolnych narzędzi programistycznych, w tym programu Notatnik.

W tym przewodniku użyjesz usługi Azure Table Storage lub Usługi Azure Cosmos DB dla funkcji tabel, które można wywołać z poziomu aplikacji PHP. Aplikacja może działać lokalnie lub w kodzie działającym w ramach roli internetowej, roli procesu roboczego lub witryny internetowej platformy Azure.

Pobieranie biblioteki klienta

1. Utwórz plik o nazwie composer.json w katalogu głównym projektu i dodaj do niego następujący kod:

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

2. Pobierz plik composer.phar do katalogu głównego.

3. Otwórz wiersz polecenia i uruchom następujące polecenie w katalogu głównym projektu:

   php composer.phar install
   

   Możesz też przejść do biblioteki klienta usługi Azure Table Storage dla języka PHP w witrynie GitHub i sklonować kod źródłowy.

Dodawanie wymaganych odwołań

Aby korzystać z usługi Azure Table Storage lub interfejsów API usługi Azure Cosmos DB, należy:

• Dodać odwołanie do pliku automatycznej ładowarki przy użyciu instrukcji require_once.
• Dodać odwołanie do wszystkich używanych klas.

Poniższy przykład pokazuje, w jaki sposób dołączyć plik automatycznej ładowarki i dodać odwołanie do klasy TableRestProxy.

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

W przykładach w tym miejscu require_once instrukcja jest zawsze wyświetlana, ale przywołuje się tylko klasy niezbędne do wykonania przykładu.

Dodawanie parametry połączenia

Możesz nawiązać połączenie z kontem usługi Azure Storage lub kontem usługi Azure Cosmos DB dla tabeli. Pobierz parametry połączenia na podstawie typu używanego konta.

Dodawanie połączenia z usługą Azure Table Storage

Aby zainicjować klienta usługi Azure Table Storage, wymagane są prawidłowe parametry połączenia. Format parametrów połączenia usługi Table Storage jest następujący:

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

Dodawanie połączenia emulatora magazynu

Aby uzyskać dostęp do emulatora usługi Azure Storage:

UseDevelopmentStorage = true

Dodawanie połączenia z usługą Azure Cosmos DB

Aby zainicjować klienta usługi Azure Cosmos DB Table, wymagane są prawidłowe parametry połączenia. Format parametrów połączenia usługi Azure Cosmos DB jest następujący:

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

Aby utworzyć klienta usługi Azure Table Storage lub Azure Cosmos DB, należy użyć klasy TableRestProxy. Możesz:

• Przekazać parametry połączenia bezpośrednio.
• Użyj klasy CloudConfigurationManager (CCM), aby sprawdzić wiele źródeł zewnętrznych dla parametry połączenia:
  • Domyślnie obsługiwane jest jedno źródło zewnętrzne — zmienne środowiskowe.
  • Możesz dodać nowe źródła, rozszerzając klasę ConnectionStringSource.

W przedstawionych tutaj przykładach parametry połączenia są przekazywane bezpośrednio.

require_once 'vendor/autoload.php';

use MicrosoftAzure\Storage\Table\TableRestProxy;

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

Tworzenie tabeli

Obiekt TableRestProxy umożliwia utworzenie tabeli przy użyciu metody createTable. Tworząc tabelę, możesz ustawić limit czasu dla usługi Table Storage. Aby uzyskać więcej informacji na temat limitu czasu usługi Table Service, zobacz Ustawianie limitów czasu dla operacji usługi 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
}

Aby uzyskać szczegółowe informacje na temat ograniczeń dotyczących nazw tabel, zobacz Understanding the Table Service Data Model (Omówienie modelu danych usługi Table Storage).

Dodawanie jednostki do tabeli

Aby dodać jednostkę do tabeli, utwórz nowy obiekt Entity i przekaż go do metody TableRestProxy-insertEntity>. Podczas tworzenia jednostki należy określić elementy i PartitionKeyRowKey. Te jednostki są unikatowymi identyfikatorami jednostki i są wartościami, które mogą być odpytywane szybciej niż inne właściwości jednostki. System używa wartości PartitionKey, aby automatycznie rozłożyć jednostki tabeli w wielu węzłach usługi Azure Storage. Jednostki z tą samą wartością PartitionKey są przechowywane w tym samym węźle. Operacje na wielu jednostkach przechowywanych w tym samym węźle działają lepiej niż w przypadku jednostek przechowywanych w różnych węzłach. Wartość RowKey to unikatowy identyfikator jednostki w partycji.

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

Aby uzyskać szczegółowe informacje na temat właściwości i typów tabel, zobacz Understanding the Table Service Data Model (Omówienie modelu danych usługi Table Storage).

Klasa TableRestProxy oferuje dwie inne metody wstawiania jednostek: insertOrMergeEntity i insertOrReplaceEntity. Aby użyć tych metod, utwórz nowy obiekt Entity i przekaż go jako parametr do jednej z tych metod. Każda metoda wstawia jednostkę, jeśli nie istnieje. Jeśli jednostka już istnieje, insertOrMergeEntity aktualizuje wartości właściwości, jeśli właściwości już istnieją i dodaje nowe właściwości, jeśli nie istnieją, podczas gdy insertOrReplaceEntity całkowicie zastępuje istniejącą jednostkę. W poniższym przykładzie pokazano, jak używać polecenia insertOrMergeEntity. Jeśli jednostka z elementami PartitionKey "tasksSeattle" i RowKey "1" jeszcze nie istnieje, ta jednostka zostanie wstawiona. Jeśli jednak już istnieje (jak pokazano w poprzednim przykładzie), DueDate właściwość zostanie zaktualizowana i Status właściwość zostanie dodana. Właściwości Description i Location również zostaną zaktualizowane, ale nowe wartości będą takie same. Jeśli te dwie ostatnie właściwości nie zostały dodane, jak pokazano w przykładzie, ale istniały w jednostce docelowej, ich istniejące wartości pozostaną niezmienione.

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

Pobieranie pojedynczej jednostki

Metoda TableRestProxy-getEntity> umożliwia pobranie pojedynczej jednostki przez wykonywanie zapytań dotyczących jej PartitionKey elementów i RowKey. W tym przykładzie klucz tasksSeattle partycji i klucz 1 wiersza są przekazywane do metody 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();

Pobieranie wszystkich jednostek w partycji

Zapytania dotyczące jednostek są tworzone przy użyciu filtrów. Aby uzyskać więcej informacji, zobacz Wykonywanie zapytań dotyczących tabel i jednostek. Aby pobrać wszystkie jednostki w partycji, użyj filtru PartitionKey eq partition_name. Następujący przykład pokazuje, w jaki sposób pobrać wszystkie jednostki w partycji tasksSeattle, przekazując filtr 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 />";
}

Pobieranie podzestawu jednostek w partycji

Schemat użyty w poprzednim przykładzie umożliwia również pobranie dowolnego podzestawu jednostek z partycji. Używany filtr określa podzestaw pobieranych jednostek. Aby uzyskać więcej informacji, zobacz Wykonywanie zapytań dotyczących tabel i jednostek. W poniższym przykładzie pokazano, jak za pomocą filtru pobrać wszystkie jednostki z określoną Location datą i DueDate mniejszą niż określona data.

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

Pobieranie podzestawu właściwości jednostki

Zapytanie umożliwia także pobranie podzestawu właściwości jednostki. Ta technika, nazywana projekcją, zmniejsza przepustowość i może poprawić wydajność zapytań, zwłaszcza w przypadku dużych jednostek. Aby określić właściwość do pobrania, przekaż nazwę właściwości do Query->addSelectField metody . Tę metodę można wywołać wiele razy, aby dodać więcej właściwości. Po wykonaniu TableRestProxy->queryEntitieszwracane jednostki będą miały tylko wybrane właściwości. Jeśli chcesz zwrócić podzestaw jednostek tabeli, użyj filtru, jak pokazano w poprzednich zapytaniach.

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

Aktualizowanie jednostki

Istniejącą jednostkę można zaktualizować przy użyciu metod Entity-setProperty> i Entity-addProperty> w jednostce, a następnie wywołać metodę TableRestProxy-updateEntity>. W poniższym przykładzie po pobraniu jednostki jedna właściwość zostanie zmodyfikowana, inna usunięta, a do tego zostanie dodana nowa właściwość. Właściwość można usunąć, ustawiając jej wartość na 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 />";
}

Usuwanie jednostki

Aby usunąć jednostkę, przekaż nazwę tabeli oraz jednostki PartitionKey i RowKey do metody 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 />";
}

W przypadku sprawdzania współbieżności można ustawić element Etag dla jednostki do usunięcia przy użyciu metody DeleteEntityOptions-setEtag> i przekazać obiekt DeleteEntityOptions do deleteEntityEntity jako czwarty parametr.

Zbiorcze operacje na tabeli

Metoda TableRestProxy-batch> umożliwia wykonywanie wielu operacji w jednym żądaniu. Wzorzec w tym miejscu obejmuje dodawanie operacji do obiektu BatchRequest, a następnie przekazywanie obiektu BatchRequest do metody TableRestProxy-batch>. Aby dodać operację do obiektu BatchRequest, możesz wywołać dowolną z następujących metod (można to zrobić wiele razy):

	Opis
addInsertEntity	Dodaje operację insertEntity
addUpdateEntity	Dodaje operację updateEntity
addMergeEntity	Dodaje operację mergeEntity
addInsertOrReplaceEntity	Dodaje operację insertOrReplaceEntity
addInsertOrMergeEntity	Dodaje operację insertOrMergeEntity
addDeleteEntity	Dodaje operację deleteEntity

Poniższy przykład przedstawia sposób wykonania operacji insertEntity i deleteEntity w ramach jednego żądania.

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

Aby uzyskać więcej informacji na temat tworzenia partii operacji, zobacz Performing Entity Group Transactions (Wykonywanie transakcji w grupach jednostek).

Usuwanie tabeli

Na koniec, aby usunąć tabelę, przekaż nazwę tabeli do metody 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 />";
}

Zawartość pokrewna

• Microsoft Azure Storage Explorer jest bezpłatną aplikacją autonomiczną oferowaną przez firmę Microsoft, która umożliwia wizualną pracę z danymi w usłudze Azure Storage w systemach Windows, macOS i Linux.
• Centrum deweloperów JĘZYKA PHP.