Freigeben über

Azure Tables-Clientbibliothek für Java – Version 12.3.16

  • Artikel

Azure Tables ist ein Dienst, der strukturierte NoSQL-Daten in der Cloud speichert und einen Schlüssel-/Attributspeicher mit einem schemalosen Design bereitstellt. Azure Tables bietet Entwicklern Flexibilität und Skalierbarkeit mit den besten Teilen der Azure-Cloud.

Quellcode | Paket (Maven) | API-Referenzdokumentation | Produktdokumentation | Proben

Erste Schritte

Einschließen des Pakets

BOM-Datei einfügen

Fügen Sie das azure-sdk-bom in Ihr Projekt ein, um die Abhängigkeit von der General Availability (GA)-Version der Bibliothek zu übernehmen. Ersetzen Sie im folgenden Codeausschnitt den Platzhalter {bom_version_to_target} durch die Versionsnummer. Weitere Informationen zur Stückliste finden Sie in der AZURE SDK-BOM-INFODATEI.

<dependencyManagement>
    <dependencies>
        <dependency>
            <groupId>com.azure</groupId>
            <artifactId>azure-sdk-bom</artifactId>
            <version>{bom_version_to_target}</version>
            <type>pom</type>
            <scope>import</scope>
        </dependency>
    </dependencies>
</dependencyManagement>

und fügen Sie dann die direkte Abhängigkeit in den Abschnitt abhängigkeiten ohne das Versionstag ein, wie unten gezeigt.

<dependencies>
    <dependency>
        <groupId>com.azure</groupId>
        <artifactId>azure-data-tables</artifactId>
    </dependency>
</dependencies>

Direkte Abhängigkeiten einfügen

Wenn Sie abhängigkeiten von einer bestimmten Version der Bibliothek übernehmen möchten, die in der Stückliste nicht vorhanden ist, fügen Sie die direkte Abhängigkeit wie folgt zu Ihrem Projekt hinzu.

<dependency>
  <groupId>com.azure</groupId>
  <artifactId>azure-data-tables</artifactId>
  <version>12.3.16</version>
</dependency>

Voraussetzungen

Erstellen eines Speicherkontos

Zum Erstellen eines Speicherkontos können Sie das Azure-Portal oder die Azure CLI verwenden.

az storage account create \
    --resource-group <resource-group-name> \
    --name <storage-account-name> \
    --location <location>

Ihre Speicherkonto-URL, die anschließend als <your-table-account-url>identifiziert wird, wird wie folgt http(s)://<storage-account-name>.table.core.windows.netformatiert.

Erstellen eines Cosmos DB-Tabellen-API-Kontos

Zum Erstellen eines Cosmos DB-Tabellen-API-Kontos können Sie das Azure-Portal oder die Azure CLI verwenden.

az cosmosdb create \
    --resource-group <resource-group-name> \
    --name <cosmosdb-account-name> \
    --capabilities EnableTable

Ihre Tabellen-API-Konto-URL, die anschließend als <your-table-account-url>identifiziert wird, wird wie folgt http(s)://<cosmosdb-account-name>.table.cosmosdb.azure.comformatiert.

Authentifizieren des Clients

Jede Anforderung, die an den Tabellendienst gesendet wird, muss mit einem Verbindungszeichenfolge, benannten Schlüsselanmeldeinformationen, Shared Access Signature oder Tokenanmeldeinformationen autorisiert werden. Die folgenden Beispiele veranschaulichen die Verwendung dieser Methoden.

Hinweis: Nur Azure Storage-API-Endpunkte unterstützen derzeit die AAD-Autorisierung über Tokenanmeldeinformationen.

Verbindungszeichenfolge

Eine Verbindungszeichenfolge enthält die Authentifizierungsinformationen, die Für den Zugriff Ihrer Anwendung auf Daten in einer Azure-Tabelle zur Laufzeit mithilfe der Autorisierung mit freigegebenem Schlüssel erforderlich sind. Ein Beispiel für die Verwendung eines Verbindungszeichenfolge mit einem finden Sie unter Authentifizieren mit einer TableServiceClientVerbindungszeichenfolge.

Sie können Ihre Verbindungszeichenfolge über das Azure-Portal (klicken Sie unter Einstellungen auf dem Blatt Portalspeicherkonto auf Zugriffsschlüsseloder unter Einstellungen auf dem Blatt "Portal Cosmos DB-Konto" unter Einstellungen) oder über die Azure CLI abrufen:

# Storage account
az storage account show-connection-string \
    --resource-group <resource-group-name> \
    --name <storage-account-name>

# Cosmos DB Table API account
az cosmosdb list-connection-strings \
    --resource-group <resource-group-name> \
    --name <cosmosdb-account-name>

Anmeldeinformationen für freigegebene Schlüssel

Die Autorisierung mit gemeinsam verwendeten Schlüsseln basiert auf Ihren Kontozugriffsschlüsseln und anderen Parametern, um eine verschlüsselte Signaturzeichenfolge zu erzeugen, die im Autorisierungsheader der Anforderung übergeben wird. Ein Beispiel für die Verwendung der Autorisierung mit benanntem Schlüssel mit einem TableServiceClientfinden Sie unter Authentifizieren mit freigegebenen Schlüsselanmeldeinformationen.

Um die Autorisierung mit benannten Schlüsseln verwenden zu können, benötigen Sie Ihren Kontonamen und die URL sowie einen Kontozugriffsschlüssel. Sie können Ihren primären Zugriffsschlüssel über das Azure-Portal (klicken Sie unter Einstellungen auf dem Blatt Portalspeicherkonto auf Zugriffsschlüsseloder unter Einstellungen auf dem Blatt "Portal Cosmos DB-Konto" unter Einstellungen) oder über die Azure CLI abrufen:

# Storage account
az storage account keys list \
    --resource-group <resource-group-name> \
    --account-name <storage-account-name>

# Cosmos DB Table API account
az cosmosdb list-keys \
    --resource-group <resource-group-name> \
    --name <cosmosdb-account-name>

Shared Access Signature (SAS)

Mit einer Shared Access Signature können Administratoren den präzisen Zugriff auf eine Azure-Tabelle delegieren, ohne den Zugriffsschlüssel direkt frei zu verwenden. Sie können steuern, auf welche Ressourcen der Client zugreifen darf, welche Berechtigungen er für diese Ressourcen besitzt und wie lange die SAS gültig ist, neben anderen Parametern. Es basiert auf Ihren Kontozugriffsschlüsseln und anderen Parametern, um eine verschlüsselte Signaturzeichenfolge zu erzeugen, die für die Anforderung in der Abfragezeichenfolge übergeben wird. Unter Authentifizieren mit einer Shared Access Signature (SAS) finden Sie ein Beispiel für die Verwendung von Shared Access Signatures mit einem TableServiceClient.

Um die SAS-Tokenautorisierung verwenden zu können, benötigen Sie Ihren Kontonamen und die URL sowie die SAS. Sie können Ihre SAS über das Azure-Portal (klicken Sie auf dem Blatt Portalspeicherkonto unter Einstellungen auf Shared Access Signature) oder über die Azure CLI abrufen:

# Account-level SAS
az storage account generate-sas \
    --account-name <storage-or-cosmosdb-account-name> \
    --services t \
    --resource-types <resource-types> \
    --permissions <permissions> \
    --expiry <expiry-date>

# Table-level SAS
az storage table generate-sas \
    --name <table-name>

TokenCredential

Azure Tables bietet die Integration in Azure Active Directory (AAD) für die identitätsbasierte Authentifizierung von Anforderungen an den Tabellendienst, wenn ein Speicherendpunkt als Ziel verwendet wird. Mit AAD können Sie die rollenbasierte Zugriffssteuerung (Role-Based Access Control, RBAC) verwenden, um Benutzern, Gruppen oder Anwendungen Zugriff auf Ihre Azure Table-Ressourcen zu gewähren.

Für den Zugriff auf eine Tabellenressource mit einem TokenCredentialmuss die authentifizierte Identität entweder über die Rolle "Mitwirkender für Speichertabellendaten" oder "Speichertabellendatenleser" verfügen.

Mit dem azure-identity Paket können Sie Anforderungen sowohl in Entwicklungs- als auch in Produktionsumgebungen nahtlos autorisieren. Weitere Informationen zur Azure AD-Integration in Azure Storage finden Sie unter Azure Identity README.

Wichtige Begriffe

  • TableServiceClient : A TableServiceClient ist ein Clientobjekt, mit dem Sie mit dem Tabellendienst interagieren können, um Tabellen zu erstellen, aufzulisten und zu löschen.
  • TableClient : A TableClient ist ein Clientobjekt, mit dem Sie mit einer bestimmten Tabelle interagieren können, um Entitäten darin zu erstellen, zu aktualisieren, zu erhalten, aufzulisten und zu löschen.
  • Tabelle : Eine Tabelle ist eine Auflistung von Entitäten. Tabellen erzwingen kein Schema für Entitäten. Das bedeutet, dass eine einzelne Tabelle Entitäten mit verschiedenen Eigenschaftensätzen enthalten kann.
  • Entität : Eine Entität ist ein Satz von Eigenschaften, ähnlich einer Datenbankzeile. Eine Entität in Azure Storage kann bis zu 1 MB groß sein. Eine Entität in Azure Cosmos DB kann bis zu 2 MB groß sein. Eine Entität verfügt über einen Partitionsschlüssel und einen Zeilenschlüssel, die die Entität innerhalb der Tabelle eindeutig identifizieren.
  • Eigenschaften : Eine Eigenschaft ist ein Name-Wert-Paar. Jede Entität kann bis zu 252 Eigenschaften zur Datenspeicherung enthalten. Jede Entität weist außerdem drei Systemeigenschaften auf, die einen Partitionsschlüssel, einen Zeilenschlüssel und einen Zeitstempel definieren.
  • Partitionsschlüssel : Der Partitionsschlüssel einer Entität identifiziert die Partition in der Tabelle, zu der die Entität gehört. Entitäten mit demselben Partitionsschlüssel können schneller abgefragt und in atomaren Operationen eingesetzt/aktualisiert werden.
  • Zeilenschlüssel : Der Zeilenschlüssel einer Entität ist ihr eindeutiger Bezeichner innerhalb einer Partition.

Häufige Verwendungen des Tabellendiensts sind:

  • Speicherung strukturierter Daten in TB-Größe zur Verarbeitung webbasierter Anwendungen
  • Speichern von Datasets, für die keine komplexen Joins, Fremdschlüssel oder gespeicherten Prozeduren erforderlich sind und die für den schnellen Zugriff denormiert werden können
  • Schnelle Datenabfrage mithilfe eines gruppierten Index
  • Zugreifen auf Daten mithilfe des OData-Protokolls

Beispiele

Authentifizieren eines Clients

Authentifizieren mit einem Verbindungszeichenfolge

Um einen Verbindungszeichenfolge zum Autorisieren Ihres Clients zu verwenden, rufen Sie die Methode des Generators connectionString mit Ihrem Verbindungszeichenfolge auf.

TableServiceClient tableServiceClient = new TableServiceClientBuilder()
    .connectionString("<your-connection-string>")
    .buildClient();

Authentifizieren mit einem freigegebenen Schlüssel

Um einen freigegebenen Schlüssel zum Autorisieren Ihres Clients zu verwenden, erstellen Sie eine instance von AzureNamedKeyCredential mit Ihrem Kontonamen und Ihrem Zugriffsschlüssel. Rufen Sie die Methode des Generators endpoint mit Ihrer Konto-URL und die credential -Methode mit dem AzureNamedKeyCredential von Ihnen erstellten Objekt auf.

AzureNamedKeyCredential credential = new AzureNamedKeyCredential("<your-account-name>", "<account-access-key>");
TableServiceClient tableServiceClient = new TableServiceClientBuilder()
    .endpoint("<your-table-account-url>")
    .credential(credential)
    .buildClient();

Authentifizieren mit einer Sas (Shared Access Signature)

Um eine SAS zum Autorisieren Ihres Clients zu verwenden, rufen Sie die Methode des Generators endpoint mit Ihrer Konto-URL und die sasToken -Methode mit Ihrer SAS auf.

TableServiceClient tableServiceClient = new TableServiceClientBuilder()
    .endpoint("<your-table-account-url>")
    .sasToken("<sas-token-string>")
    .buildClient();

Authentifizieren mit Tokenanmeldeinformationen

Um Ihren Client über AAD zu autorisieren, erstellen Sie eine instance einer AnmeldeinformationsklasseTokenCredential, die implementiert. Rufen Sie die Methode des Generators endpoint mit Ihrer Konto-URL und die credential -Methode mit dem TokenCredential von Ihnen erstellten Objekt auf.

TokenCredential tokenCredential = new DefaultAzureCredentialBuilder().build();
TableServiceClient tableServiceClient = new TableServiceClientBuilder()
    .endpoint("<your-table-account-url>")
    .credential(tokenCredential)
    .buildClient();

Erstellen, Auflisten und Löschen von Azure-Tabellen

Erstellen eines TableServiceClient

Erstellen Sie eineTableServiceClient, indem Sie eine instance von TableServiceClientBuilder erstellen und dann die Methoden des Generators buildClient oder buildAsyncClient aufrufen.

TableServiceClient tableServiceClient = new TableServiceClientBuilder()
    .connectionString("<your-connection-string>") // or use any of the other authentication methods
    .buildClient();

Erstellen einer Tabelle

Erstellen Sie eine Tabelle, indem Sie die TableServiceClientMethode 's createTable aufrufen. Ein TableClient wird zurückgegeben, dieser Client ermöglicht das Ausführen von Vorgängen für die Tabelle. Eine Ausnahme wird ausgelöst, wenn eine Tabelle mit dem angegebenen Namen vorhanden ist.

TableClient tableClient = tableServiceClient.createTable(tableName);

Alternativ können Sie die -Methode aufrufen, die createTableIfNotExists die Tabelle nur dann erstellt, wenn keine solche Tabelle vorhanden ist und keine Ausnahme ausgelöst wird. A TableClient wird ebenfalls zurückgegeben.

TableClient tableClient = tableServiceClient.createTableIfNotExists(tableName);

Auflisten von Tabellen

Auflisten oder Abfragen vorhandener Tabellen, indem Sie die TableServiceClientMethode "slistTables" aufrufen und optional eine ListTablesOptions instance übergeben, um die Abfrageergebnisse zu filtern oder einzuschränken. Weitere Informationen zu unterstützten Abfrageoptionen finden Sie unter Unterstützte Abfrageoptionen .

ListTablesOptions options = new ListTablesOptions()
    .setFilter(String.format("TableName eq '%s'", tableName));

for (TableItem tableItem : tableServiceClient.listTables(options, null, null)) {
    System.out.println(tableItem.getName());
}

Löschen einer Tabelle

Löschen Sie eine Tabelle, indem Sie die TableServiceClientMethode 's deleteTable aufrufen.

tableServiceClient.deleteTable(tableName);

Erstellen, Auflisten und Löschen von Tabellenentitäten

Erstellen eines TableClient

Erstellen Sie eineTableClient, indem Sie eine instance von TableClientBuildererstellen, indem Sie die -Methode des Generators tableName mit dem Namen der Tabelle aufrufen und dann deren buildClient Methoden oder buildAsyncClient aufrufen.

TableClient tableClient = new TableClientBuilder()
    .connectionString("<your-connection-string>") // or use any of the other authentication methods
    .tableName(tableName)
    .buildClient();

Alternativ kann ein TableClient aus einem vorhandenen TableServiceClient abgerufen werden, indem seine getTableClient -Methode aufgerufen wird.

TableClient tableClient = tableServiceClient.getTableClient(tableName);

Erstellen einer Entität

Erstellen Sie einen neuen TableEntity instance, indem Sie den Partitionsschlüssel und den Zeilenschlüssel der zu erstellenden Entität bereitstellen und optional Eigenschaften zum erstellten Objekt hinzufügen. Übergeben Sie dann das -Objekt an die TableClientMethode "s createEntity ". Eine Ausnahme wird ausgelöst, wenn eine Entität mit dem angegebenen Partitionsschlüssel und Zeilenschlüssel in der Tabelle vorhanden ist.

TableEntity entity = new TableEntity(partitionKey, rowKey)
    .addProperty("Product", "Marker Set")
    .addProperty("Price", 5.00)
    .addProperty("Quantity", 21);

tableClient.createEntity(entity);

Auflisten von Entitäten

Auflisten oder Abfragen der Entitäten in der Tabelle, indem Sie die TableClient-Methode der -listEntitiesMethode aufrufen und optional eine ListEntitiesOptions instance übergeben, um die Abfrageergebnisse zu filtern, auszuwählen oder einzuschränken. Weitere Informationen zu unterstützten Abfrageoptionen finden Sie unter Unterstützte Abfrageoptionen .

List<String> propertiesToSelect = new ArrayList<>();
propertiesToSelect.add("Product");
propertiesToSelect.add("Price");

ListEntitiesOptions options = new ListEntitiesOptions()
    .setFilter(String.format("PartitionKey eq '%s'", partitionKey))
    .setSelect(propertiesToSelect);

for (TableEntity entity : tableClient.listEntities(options, null, null)) {
    Map<String, Object> properties = entity.getProperties();
    System.out.printf("%s: %.2f%n", properties.get("Product"), properties.get("Price"));
}

Löschen einer Entität

Löschen Sie eine Entität, indem Sie die TableClientMethode 's deleteEntity aufrufen.

tableClient.deleteEntity(partitionKey, rowKey);

Problembehandlung

Allgemein

Wenn Sie mit dem Tabellendienst mithilfe der Azure Tables-Bibliothek für Java interagieren, entsprechen die vom Dienst zurückgegebenen Fehler den gleichen HTTP-status-Codes, die für REST-API-Anforderungen zurückgegeben werden.

Wenn Sie beispielsweise versuchen, eine bereits vorhandene Tabelle zu erstellen, wird ein 409 Fehler zurückgegeben, der auf "Konflikt" hinweist.

// Create the table if it doesn't already exist.
tableServiceClient.createTableIfNotExists(tableName);

// Now attempt to create the same table unconditionally.
try {
    tableServiceClient.createTable(tableName);
} catch (TableServiceException e) {
    System.out.println(e.getResponse().getStatusCode()); // 409
}

Protokollierung

Die Aktivierung der Protokollierung kann hilfreiche Informationen über Fehler aufdecken. Um ein Protokoll mit HTTP-Anforderungen und -Antworten anzuzeigen, legen Sie die Umgebungsvariable AZURE_LOG_LEVEL auf die gewünschte Ausführlichkeit fest. Eine Beschreibung der verfügbaren Protokollebenen finden Sie unter LogLevel .

Nächste Schritte

Erste Schritte mit unseren Tabellenbeispielen.

Mitwirken

Beiträge und Vorschläge für dieses Projekt sind willkommen. Für die meisten Beiträge ist die Zustimmung zu einer Lizenzvereinbarung für Mitwirkende (Contributor License Agreement, CLA) erforderlich, in der Sie erklären, dass Sie dazu berechtigt sind, uns die Rechte für die Nutzung Ihres Beitrags zu erteilen, und dies auch tun.

Wenn Sie einen Pull Request (PR) übermitteln, überprüft ein CLA-Bot automatisch, ob Sie eine Lizenzvereinbarung bereitstellen und den PR entsprechend ergänzen müssen (z.B. mit einer Bezeichnung oder einem Kommentar). Führen Sie einfach die Anweisungen des Bots aus. Sie müssen dies nur einmal für alle Repositorys ausführen, die unsere CLA verwenden.

Für dieses Projekt gelten die Microsoft-Verhaltensregeln für Open Source (Microsoft Open Source Code of Conduct). Weitere Informationen finden Sie in den häufig gestellten Fragen zum Verhaltenskodex. Sie können sich auch an opencode@microsoft.com wenden, wenn Sie weitere Fragen oder Anmerkungen haben.

Aufrufe