Jak skonfigurować globalne indeksy pomocnicze usługi Azure Cosmos DB for NoSQL (wersja zapoznawcza)

2025-05-19

DOTYCZY: NoSQL

Ważne

Globalne indeksy pomocnicze usługi Azure Cosmos DB for NoSQL są obecnie dostępne w wersji zapoznawczej. Ta wersja zapoznawcza jest udostępniana bez umowy dotyczącej poziomu usług. Obecnie nie zalecamy używania globalnych indeksów pomocniczych dla obciążeń produkcyjnych. Niektóre funkcje tej wersji zapoznawczej mogą nie być obsługiwane lub mogą mieć ograniczone możliwości. Aby uzyskać więcej informacji, zobacz dodatkowe warunki użytkowania dla wersji zapoznawczych platformy Microsoft Azure.

Globalne indeksy pomocnicze zapewniają zaawansowany sposób optymalizowania wydajności zapytań i upraszczania logiki aplikacji przez przechowywanie danych przy użyciu innego klucza partycji i/lub modelu danych. W tym artykule opisano sposób tworzenia globalnych indeksów pomocniczych i sposobu ich używania w celu uniknięcia zapytań obejmujących wiele partycji.

Wymagania wstępne

Istniejące konto usługi Azure Cosmos DB.
- Jeśli masz subskrypcję platformy Azure, utwórz nowe konto.
- Jeśli nie masz subskrypcji Azure, przed rozpoczęciem utwórz darmowe konto.
- Alternatywnie możesz wypróbować usługę Azure Cosmos DB bezpłatnie przed zatwierdzeniem.

Włączanie globalnych indeksów pomocniczych

Włącz globalną funkcję indeksu pomocniczego dla konta usługi Azure Cosmos DB. Przed włączeniem globalnych indeksów pomocniczych należy włączyć ciągłe kopie zapasowe dla konta.

Portal Azure
Interfejs wiersza polecenia platformy Azure

Zaloguj się do witryny Azure Portal.
Przejdź do konta usługi Azure Cosmos DB for NoSQL.
W menu zasobów wybierz pozycję Ustawienia.
Przejdź do strony Funkcje . Następnie wybierz pozycję Globalny indeks pomocniczy dla interfejsu API NoSQL (wersja zapoznawcza) i włącz.

Użyj interfejsu wiersza polecenia platformy Azure, aby włączyć funkcję globalnego indeksu pomocniczego przy użyciu natywnego polecenia lub operacji interfejsu API REST na koncie usługi Azure Cosmos DB for NoSQL.

Zaloguj się do Azure CLI.
```
az login
```
Uwaga / Notatka

Wymaga to interfejsu wiersza polecenia platformy Azure. Zobacz , jak zainstalować interfejs wiersza polecenia platformy Azure.

Zdefiniuj zmienne dla grupy zasobów i nazwy konta istniejącego konta usługi Azure Cosmos DB dla noSQL.

# Variable for resource group name
$resourceGroupName="<resource-group-name>"

# Variable for account name
$accountName="<account-name>"

# Variable for Azure subscription
$subscriptionId="<subscription-id>"

Utwórz nowy plik JSON o nazwie capabilities.json przy użyciu manifestu możliwości.
```
{
  "properties": {
    "enableMaterializedViews": true
  }
}
```
Uwaga / Notatka

Nazwa właściwości umożliwiająca włączenie globalnych indeksów pomocniczych to enableMaterializedViews, czyli była nazwa funkcji. Włączenie zmaterializowanych widoków umożliwi globalne indeksy pomocnicze.

Pobierz identyfikator konta i zapisz go w zmiennej powłoki o nazwie $accountId.

$accountId="/subscriptions/$subscriptionId/resourceGroups/$resourceGroupName/providers/Microsoft.DocumentDB/databaseAccounts/$accountName"

Włącz funkcję podglądu globalnego indeksu pomocniczego dla konta, używając interfejsu API REST i polecenia az rest z czasownikiem HTTP PATCH.

az rest \
    --method PATCH \
    --uri "https://management.azure.com/$accountId/?api-version=2022-11-15-preview" \
    --body @capabilities.json

Tworzenie globalnego indeksu pomocniczego

Po włączeniu globalnej funkcji indeksu pomocniczego można utworzyć globalne indeksy pomocnicze.

Tworzenie kontenera źródłowego

Globalne indeksy pomocnicze przechowują kopię danych z kontenera źródłowego. Przed utworzeniem globalnego indeksu pomocniczego utwórz kontener źródłowy, na podstawie którego zostanie utworzony kontener indeksu. Jeśli masz już kontener na koncie usługi Azure Cosmos DB, którego chcesz użyć jako źródła, możesz pominąć te kroki.

Użyj portalu Azure, zestawów SDK platformy Azure, interfejsu wiersza polecenia Azure lub interfejsu API REST, aby utworzyć kontener źródłowy nazwany gsi-src, z /customerId jako ścieżką klucza partycji.

Uwaga / Notatka

Pole /customerId jest używane tylko jako przykład w tym artykule. W przypadku własnych kontenerów wybierz klucz partycji, który najlepiej odpowiada Twojemu rozwiązaniu.
Wstaw kilka elementów w kontenerze źródłowym. Aby postępować zgodnie z przykładami przedstawionymi w tym artykule, upewnij się, że elementy mają customerId pola i emailAddress . Przykładowy element może wyglądać następująco:
```
{
  "id": "eaf0338e-2b61-4163-822f-7bef75bf51de",
  "customerId": "36c7cc3d-1709-45c6-819f-10e5586a6cb7",
  "emailAddress": "justine@contoso.com",
  "name": "Justine"
}
```
Wskazówka

W tym przykładzie kontener źródłowy zostanie wypełniony przykładowymi danymi przed dodaniem kontenera indeksów. Możesz również utworzyć globalny indeks pomocniczy z pustego kontenera źródłowego.

Tworzenie globalnego pomocniczego kontenera indeksów

Po utworzeniu kontenera źródłowego można utworzyć globalny kontener indeksu pomocniczego przy użyciu witryny Azure Portal lub interfejsu wiersza polecenia platformy Azure.

Portal Azure
Interfejs wiersza polecenia platformy Azure

Przejdź do Eksploratora danych na koncie usługi Azure Cosmos DB. Wybierz kontener źródłowy, gsi-src w tym przykładzie i z listy rozwijanej wybierz pozycję Nowy globalny indeks pomocniczy .
Identyfikator kontenera źródłowego zostanie automatycznie wypełniony. W polu Identyfikator kontenera indeksu wprowadź wartość gsi-target.
W polu Definicja globalnego indeksu wtórnego wprowadź wartość SELECT c.customerId, c.emailAddress FROM c.
W polu Klucz partycji wprowadź wartość /emailAddress.
Globalne kontenery indeksów pomocniczych muszą używać przepływności z automatycznym skalowaniem. Skonfiguruj inne ustawienia kontenera, które chcesz, i wybierz przycisk OK , aby utworzyć globalny kontener indeksu pomocniczego.
Po utworzeniu globalnego pomocniczego kontenera indeksów dane są automatycznie synchronizowane z kontenera źródłowego. Spróbuj wykonać operacje tworzenia, aktualizowania i usuwania w kontenerze źródłowym. Zobaczysz te same zmiany propagowane do elementów w globalnym indeksie wtórnym.

Utwórz globalny indeks pomocniczy o nazwie gsi-target z ścieżką klucza partycji, która różni się od kontenera źródłowego. W tym przykładzie określ /emailAddress jako ścieżkę klucza partycji dla kontenera gsi-target .
1. Utwórz manifest definicji dla globalnego indeksu pomocniczego i zapisz go w pliku JSON o nazwie gsi-definition.json. Globalne kontenery indeksów pomocniczych muszą używać przepływności z automatycznym skalowaniem. Na tym etapie można również zdefiniować inne istotne właściwości kontenera, takie jak zasady indeksowania.
```
{
  "location": "West US 2",
  "tags": {},
  "properties": {
    "resource": {
      "id": "gsi-target",
      "partitionKey": {
        "paths": [
          "/emailAddress"
        ]
      },
      "materializedViewDefinition": {
        "sourceCollectionId": "gsi-src",
        "definition": "SELECT c.customerId, c.emailAddress FROM c"
      }
    },
    "options": {
      "autoscaleSettings": {
        "maxThroughput": 1000
      }
    }
  }
}        
```
Ważne

Zwróć uwagę, że ścieżka klucza partycji jest ustawiona jako /emailAddress.

Właściwość służąca do definiowania globalnych indeksów pomocniczych to materializedViewDefinition, czyli była nazwa tej funkcji. Element sourceCollectionId definiuje kontener źródłowy i definition zawiera zapytanie określające model danych kontenera indeksów. Nie można zmienić globalnego pomocniczego kontenera źródłowego indeksu i kwerendy definicji po utworzeniu. Dowiedz się więcej na temat definiowania globalnych indeksów pomocniczych i ograniczeń zapytań.

Następnie utwórz wywołanie interfejsu API REST w celu utworzenia globalnego indeksu pomocniczego zgodnie z definicją w pliku gsi-definition.json . Użyj Azure CLI, aby wykonać wywołanie API REST.

Utwórz zmienną dla nazwy globalnego indeksu pomocniczego i nazwy źródłowej bazy danych:

# This should match the resource ID you defined in your json file
$gsiContainerName = "gsi-target"

# Database name for the source and index containers
$databaseName = "<Database that contains source container>"

# Azure Cosmos DB account name
$accountName = "<Azure Cosmos DB account name>"

# Resource name for your Azure Cosmos DB account
$resourceGroupName = "<Resource group for Azure Cosmos DB account>"

# Subscription id for your Azure Cosmos DB account
$subscriptionId = "<Subscription id>"

Skonstruuj identyfikator zasobu przy użyciu tych zmiennych.

$accountId = "/subscriptions/$subscriptionId/resourceGroups/$resourceGroupName/providers/Microsoft.DocumentDB/databaseAccounts/$accountName"

Wywołaj interfejs API REST, aby utworzyć globalny indeks pomocniczy:

az rest \
    --method PUT \
    --uri "https://management.azure.com$accountId/sqlDatabases/$databaseName/containers/$gsiContainerName/?api-version=2022-11-15-preview" \
    --body @gsi-definition.json \
    --headers content-type=application/json \
    --output json \
    --verbose

Sprawdź stan tworzenia globalnego pomocniczego kontenera indeksów przy użyciu interfejsu API REST:

az rest \
    --method GET \
    --uri "https://management.azure.com$accountId/sqlDatabases/$databaseName/containers/$gsiContainerName/?api-version=2022-11-15-preview" \
    --headers content-type=application/json \
    --query "{mvCreateStatus: properties.Status}"

Po utworzeniu globalnego indeksu pomocniczego dane są automatycznie synchronizowane z kontenera źródłowego. Spróbuj wykonać operacje tworzenia, aktualizowania i usuwania w kontenerze źródłowym. Zobaczysz te same zmiany propagowane do elementów w globalnym indeksie wtórnym.

Wykonywanie zapytań o dane z globalnych indeksów pomocniczych

W tym przykładzie mamy kontener źródłowy podzielony na partycje według customerId oraz globalny kontener indeksu pomocniczego partycjonowany według emailAddress. Bez kontenera indeksów zapytania, które obejmują tylko emailAddress, byłyby zapytaniami krzyżowymi między partycjami. Teraz mogą być uruchamiane względem globalnego indeksu pomocniczego, aby zwiększyć wydajność.

Wykonywanie zapytań dotyczących danych z globalnych indeksów pomocniczych jest podobne do wykonywania zapytań dotyczących danych z dowolnego innego kontenera. Do wykonywania zapytań dotyczących danych w globalnych indeksach pomocniczych można użyć witryny Azure Portal, zestawów SDK platformy Azure lub interfejsu API REST.

Container container = client.GetDatabase("gsi-db").GetContainer("gsi-target");

FeedIterator<MyClass> myQuery = container.GetItemQueryIterator<MyClass>(new QueryDefinition("SELECT * FROM c WHERE c.emailAddress = 'justine@contoso.com'"));

CosmosAsyncDatabase container = client.getDatabase("gsi-db");
CosmosAsyncContainer container = database.getContainer("gsi-target");

CosmosPagedFlux<MyClass> pagedFluxResponse = container.queryItems(
        "SELECT * FROM c WHERE c.emailAddress = 'justine@contoso.com'", null, MyClass.class);

const database = client.database("gsi-db");
const container = database.container("gsi-target");

const querySpec = {
    query: "SELECT * FROM c WHERE c.emailAddress = 'justine@contoso.com'"
 };
const { resources: items } = await container.items
    .query(querySpec)
    .fetchAll();

database = client.get_database_client("gsi-db")
container = database.get_container_client("gsi-target")

query = "SELECT * FROM c WHERE c.emailAddress = 'justine@contoso.com'"
container.query_items(
    query=query
)

gsiContainer, err := client.NewContainer("gsi-db", "gsi-target")

pager := gsiContainer.NewQueryItemsPager("select * from c where c.state = @state", azcosmos.NewPartitionKey(), &azcosmos.QueryOptions{
	QueryParameters: []azcosmos.QueryParameter{
		{
			Name:  "@state",
			Value: "Alaska",
		},
	},
})

if pager.More() {
  // Iterate through the results
  // page, _ := pager.NextPage(context.Background())
}

Dalsze kroki

Modelowanie danych i partycjonowanie globalnego indeksu pomocniczego — omówienie