kvp in attributeList)
{
string attributeName = kvp.Key;
AttributeValue value = kvp.Value;
Console.WriteLine(
attributeName + " " +
(value.S == null ? "" : "S=[" + value.S + "]") +
(value.N == null ? "" : "N=[" + value.N + "]") +
(value.SS == null ? "" : "SS=[" + string.Join(",", value.SS.ToArray()) + "]") +
(value.NS == null ? "" : "NS=[" + string.Join(",", value.NS.ToArray()) + "]") +
(value.B == null ? "" : "B=[" + FromGzipMemoryStream(value.B) + "]")
);
}
Console.WriteLine("************************************************");
}
private static MemoryStream ToGzipMemoryStream(string value)
{
MemoryStream output = new MemoryStream();
using (GZipStream zipStream = new GZipStream(output, CompressionMode.Compress, true))
using (StreamWriter writer = new StreamWriter(zipStream))
{
writer.Write(value);
}
return output;
}
private static string FromGzipMemoryStream(MemoryStream stream)
{
using (GZipStream zipStream = new GZipStream(stream, CompressionMode.Decompress))
using (StreamReader reader = new StreamReader(zipStream))
{
return reader.ReadToEnd();
}
}
}
}
```
# Amélioration de l’accès aux données avec les index secondaires dans DynamoDB
Amazon DynamoDB fournit un accès rapide aux éléments d’une table en spécifiant des valeurs de clé principale. Cependant, il serait utile pour de nombreuses applications de disposer d’une ou de plusieurs clés secondaires (ou alternatives) permettant un accès efficace aux données présentant d’autres attributs que la clé primaire. Pour ce faire, vous pouvez créer un ou plusieurs index secondaires pour une table, et émettre des demandes `Query` ou `Scan` sur ces index.
Un *index secondaire* est une structure de données qui contient un sous-ensemble d’attributs d’une table, ainsi qu’une autre clé pour prendre en charge des opérations `Query`. Vous pouvez récupérer les données de l’index à l’aide d’un `Query`, globalement de la même manière que vous utilisez `Query` avec une table. Une table peut avoir plusieurs index secondaires, ce qui permet à vos applications d’accéder à de nombreux modèles de requête différents.
**Note**
Vous pouvez également `Scan` un index, globalement de la même manière que vous le feriez pour `Scan` une table.
L’accès intercompte pour les opérations d’analyse d’index secondaires n’est actuellement pas pris en charge par les [politiques basées sur les ressources](access-control-resource-based.md).
Chaque index secondaire est associé à une table dont il extrait ses données. Il s’agit de la *table de base* de l’index. Lorsque vous créez un index, vous définissez une autre clé pour cet index (clé de partition et clé de tri). Vous définissez également les attributs qui doivent être *projetés*, ou copiés de la table de base vers l’index. DynamoDB copie ces attributs dans l’index, ainsi que les attributs de clé primaire de la table de base. Vous pouvez ensuite interroger ou analyser l’index de la même manière que vous procéderiez avec une table.
DynamoDB grère automatiquement chaque index secondaire . Lorsque vous ajoutez, modifiez ou supprimez des éléments dans la table de base, tous les index de cette table sont également mis à jour pour refléter ces modifications.
DynamoDB prend en charge deux types d’index secondaires :
+ **[Index secondaire global](GSI.html) – **Index avec une clé de partition et une clé de tri pouvant différer de celles de la table de base. Un index secondaire global est considéré comme « global », car les requêtes sur l’index peuvent couvrir toutes les données de la table de base, sur toutes les partitions. Un index secondaire global est stocké dans son propre espace de partition à l’écart de la table de base, et est mis à l’échelle séparément de celle-ci.
+ **[Index secondaire local](LSI.html) – **Index avec la même clé de partition que la table de base, mais une clé de tri différente. Un index secondaire est « local » dans la mesure où la portée de chacune de ses partitions correspond à une partition de la table de base ayant la même valeur de clé de partition.
Pour une comparaison des index secondaires globaux et des index secondaires locaux, regardez cette vidéo.
[](http://www.youtube.com/watch?v=https://www.youtube.com/embed/BkEu7zBWge8)
**Topics**
+ [Utilisation d’index secondaires globaux dans DynamoDB](GSI.md)
+ [Index locaux secondaires](LSI.md)
Vous devez tenir compte des exigences de votre application lorsque vous déterminez le type d’index à utiliser. Le tableau suivant montre les principales différences entre un index secondaire global et un index secondaire local.
****
| Caractéristiques | GSI | Index secondaire local |
| --- | --- | --- |
| Schéma de clé | La clé primaire d’un index secondaire global peut être simple (clé de partition) ou composite (clé de partition et clé de tri). | La clé primaire d’un index secondaire local doit être composite (clé de partition et clé de tri). |
| Attributs de clé | La clé de partition d’index et la clé de tri (le cas échéant) peuvent être n’importe quels attributs de table de base de type chaîne, nombre ou binaire. | La clé de partition de l’index est le même attribut que la clé de partition de la table de base. La clé de tri peut être n’importe quel attribut de la table de base, de type chaîne, nombre ou binaire. |
| Restrictions de taille par valeur de clé de partition | Les index secondaires globaux ne font l’objet d’aucune restriction de taille . | Pour chaque valeur de clé de partition, la taille totale de tous les éléments indexés doit être inférieure ou égale à 10 Go. |
| Opérations d’index en ligne | Vous pouvez créer des index secondaires globaux au moment où vous créez une table. Vous pouvez ajouter un index secondaire global à une table ou en supprimer un. Pour de plus amples informations, veuillez consulter [Gestion des index secondaires globaux dans DynamoDB](GSI.OnlineOps.md). | Vous créez des index secondaires locaux au moment où vous créez une table. Vous ne pouvez ni ajouter un index secondaire local à une table, ni en supprimer un. |
| Requêtes et partitions | Un index secondaire global vous permet d’interroger une table entière, toutes partitions incluses. | Un index secondaire local vous permet d’interroger une seule partition en spécifiant la valeur de clé de partition dans la requête. |
| Cohérence en lecture | Les requêtes sur les index secondaires globaux ne prennent en charge que la cohérence éventuelle. | Lorsque vous interrogez un index secondaire local, vous avez le choix entre la cohérence éventuelle ou la cohérence forte. |
| Consommation de débit alloué | Chaque index secondaire global a ses propres paramètres de débit approvisionné pour les activités de lecture et d’écriture. Les requêtes ou analyses sur un index secondaire global consomment des unités de capacité de l’index, pas de la table de base. Il en va de même pour des mises à jour d’index secondaire global résultant d’écritures dans la table. Un index secondaire global associé à des tables globales consomme des unités de capacité d’écriture. | Les requêtes ou analyses sur un index secondaire local consomment des unités de capacité de lecture de la table de base. Lorsque vous écrivez des données dans une table, ses index secondaires locaux sont mis à jour, ce qui entraîne une consommation des unités de capacité d’écriture à partir de la table de base. Un index secondaire local associé à des tables globales consomme des unités de capacité d’écriture répliquées. |
| Attributs projetés | Les requêtes ou analyses d’index secondaire global ne vous permettent d’interroger que les attributs projetés dans l’index. DynamoDB n’extrait aucun attribut de la table. | Si vous interrogez ou analysez un index secondaire local, vous pouvez demander des attributs qui ne sont pas projetés dans l’index. DynamoDB extrait automatiquement ces attributs de la table. |
Si vous souhaitez créer plus d’une table avec des index secondaires, vous devez le faire de manière séquentielle. Par exemple, vous créez la première table et attendez qu’elle devienne `ACTIVE`, vous créez la table suivante et attendez qu’elle devienne `ACTIVE`, et ainsi de suite. Si vous essayez de créer simultanément plus d’une table avec un index secondaire, DynamoDB renvoie une `LimitExceededException`.
Chaque index secondaire utilise la même [classe de table](HowItWorks.TableClasses.html) et le même [mode de capacité](capacity-mode.md) que la table de base à laquelle il est associé. Pour chaque index secondaire, vous devez spécifier les informations suivantes :
+ Type d’index à créer : index secondaire global ou un index secondaire local.
+ Un nom pour l’index. Les règles de dénomination pour les index sont identiques à celles pour les tables, comme indiqué dans [Quotas dans Amazon DynamoDB](ServiceQuotas.md). Le nom doit être unique pour la table de base à laquelle il est associé, mais vous pouvez utiliser le même nom pour des index qui sont associés à d’autres tables de base.
+ Le schéma de clés pour l’index. Chaque attribut du schéma de clé d’index doit être un attribut de niveau supérieur de type `String`, `Number` ou `Binary`. D’autres types de données, y compris les documents et les jeux, ne sont pas autorisés. Les autres exigences pour le schéma de clé dépendent du type d’index :
+ Pour un index secondaire global, la clé de partition peut être n’importe quel attribut scalaire de la table de base. Une clé de tri est facultative et peut également être n’importe quel attribut scalaire de la table de base.
+ Pour un index secondaire local, la clé de partition doit être la même que celle de la table de base, et la clé de tri doit être un attribut de la table de base autre qu’une clé.
+ Attributs supplémentaires, le cas échéant, à projeter de la table de base vers l’index. Ces attributs sont en plus des attributs clés de la table, qui sont automatiquement projetés dans chaque index. Vous pouvez projeter des attributs de n’importe quel type de données, y compris scalaires, documents et jeux.
+ Les paramètres de débit alloué pour l’index, si nécessaire :
+ Pour un index secondaire global, vous devez spécifier des paramètres d’unité de capacité de lecture et d’écriture. Ces paramètres de débit alloué sont indépendants des paramètres de la table de base.
+ Pour un index secondaire local, vous n’avez pas besoin de spécifier des paramètres d’unité de capacité de lecture et d’écriture. Toute opération de lecture et d’écriture sur un index secondaire local tire les paramètres de débit approvisionné de sa table de base.
Pour bénéficier d’une flexibilité de requête maximum, vous pouvez créer jusqu’à 20 index secondaires globaux (quota par défaut) et 5 index secondaires locaux par table.
Pour obtenir la liste détaillée des index secondaires sur une table, utilisez l’opération `DescribeTable`. L’opération `DescribeTable` renvoie le nom, la taille de stockage et le nombre d’éléments pour chaque index secondaire sur la table. Ces valeurs ne sont pas mises à jour en temps réel, mais elles sont actualisées environ toutes les six heures.
Vous pouvez accéder aux données dans un index secondaire à l’aide de l’opération `Query` ou `Scan`. Vous devez spécifier le nom de la table de base et le nom de l’index que vous souhaitez utiliser, les attributs à renvoyer dans les résultats, ainsi que tous les filtres ou expressions de condition que vous souhaitez appliquer. DynamoDB peut renvoyer les résultats dans l’ordre croissant ou décroissant.
Lorsque vous supprimez une table, tous les index associés à cette table sont également supprimés.
Pour connaître les bonnes pratiques, consultez [Bonnes pratiques d’utilisation d’index secondaires dans DynamoDB](bp-indexes.md).
# Utilisation d’index secondaires globaux dans DynamoDB
Certaines applications peuvent avoir besoin d’exécuter de nombreux types de requêtes, à l’aide de divers attributs comme critères de requête. Pour prendre en charge ces exigences, vous pouvez créer un ou plusieurs *index secondaires globaux* et émettre des demandes `Query` sur ces index dans Amazon DynamoDB.
**Topics**
+ [Étape 6 : Utiliser un index secondaire global](#GSI.scenario)
+ [Projections d’attribut](#GSI.Projections)
+ [Schéma de clé à attributs multiples](#GSI.MultiAttributeKeys)
+ [Lecture de données à partir d’un index secondaire global](#GSI.Reading)
+ [Synchronisation des données entre les tables et les index secondaires globaux](#GSI.Writes)
+ [Classes de tables avec index secondaire global](#GSI.tableclasses)
+ [Considérations sur le débit alloué pour les index secondaires globaux](#GSI.ThroughputConsiderations)
+ [Considérations relatives au stockage pour les index secondaires globaux](#GSI.StorageConsiderations)
+ [Motifs de design](GSI.DesignPatterns.md)
+ [Gestion des index secondaires globaux dans DynamoDB](GSI.OnlineOps.md)
+ [Détection et correction des violations de clé d’index dans DynamoDB](GSI.OnlineOps.ViolationDetection.md)
+ [Utilisation d'index secondaires globaux : Java](GSIJavaDocumentAPI.md)
+ [Utilisation d'index secondaires globaux : .NET](GSILowLevelDotNet.md)
+ [Gestion des index secondaires globaux dans DynamoDB à l’aide de l’AWS CLI](GCICli.md)
## Étape 6 : Utiliser un index secondaire global
À des fins d’illustration, considérons une table nommée `GameScores` qui assure le suivi des utilisateurs et enregistre les scores d’une application de jeux pour appareils mobiles. Chaque élément dans `GameScores` est identifié par une clé de partition (`UserId`) et une clé de tri (`GameTitle`). Le schéma suivant illustre la façon dont les éléments de la table seront organisés. (Tous les attributs ne sont pas affichés.)
![\[GameScores table contenant une liste de l'identifiant utilisateur, du titre, du score, de la date et des victoires/défaites.\]](http://docs.aws.amazon.com/fr_fr/amazondynamodb/latest/developerguide/images/GSI_01.png)
Supposons maintenant que vous vouliez écrire une application de classement pour afficher les meilleurs scores de chaque partie. Une requête ayant spécifié les attributs clé (`UserId` et `GameTitle`) serait très efficace. Cependant, si l’application a besoin d’extraire les données depuis `GameScores` en fonction de `GameTitle` uniquement, elle nécessiterait l’utilisation d’une opération `Scan`. Lorsque plusieurs éléments sont ajoutés à la table, les analyses de toutes les données deviennent lentes et inefficaces. Cela rend difficile la réponse aux questions suivantes :
+ Quel est le meilleur score jamais enregistré pour le jeu Meteor Blasters ?
+ Quel utilisateur a le score le plus élevé pour Galaxy Invaders ?
+ Quel est le taux plus élevé du nombre de victoires par rapport au nombre de pertes ?
Afin d’accélérer les requêtes sur des attributs autres que de clé, vous pouvez créer un index secondaire global. Un index secondaire global contient une sélection d’attributs de la table de base, mais ils sont organisés selon une clé primaire différente de celle de la table. La clé d’index n’a pas besoin d’avoir l’un des attributs de clé de la table. Elle n’a même pas besoin d’avoir le même schéma de clé qu’une table.
Par exemple, vous pouvez créer un index secondaire global nommé `GameTitleIndex`, avec une clé de partition `GameTitle` et une clé de tri `TopScore`. Comme les attributs de la clé primaire de la table de base sont toujours projetés sur un index, l’attribut `UserId` est également présent. Le schéma suivant illustre ce à quoi l’index `GameTitleIndex` doit ressembler.
![\[GameTitleIndex tableau contenant une liste de titres, de scores et d'identifiants d'utilisateur.\]](http://docs.aws.amazon.com/fr_fr/amazondynamodb/latest/developerguide/images/GSI_02.png)
Maintenant, vous pouvez interroger `GameTitleIndex` et obtenir facilement les scores de Meteor Blasters. Les résultats sont triés sur les valeurs de la clé de tri, `TopScore`. Si vous définissez le paramètre `ScanIndexForward` sur la valeur false, les résultats sont retournés par ordre décroissant, de telle sorte que le meilleur score est retourné en premier.
Chaque index secondaire global doit avoir une clé de partition et peut avoir une clé de tri facultative. Le schéma de la clé d’index peut être différent de celui de la table de base. Vous pouvez disposer d’une table avec une clé primaire simple (clé de partition), et créer un index secondaire global avec une clé primaire composite (clé de partition et clé de tri), ou inversement. Les attributs de clé d’index peuvent se composer de n’importe lequel des attributs `String`, `Number` ou `Binary` de niveau supérieur de la table de base. Les autres types scalaires, types de document et types d’ensemble ne sont pas autorisés.
Vous pouvez projeter d’autres attributs de table de base sur l’index si vous le souhaitez. Lorsque vous interrogez l’index, DynamoDB peut extraire ces attributs projetés de façon efficace. Cependant, les interrogations d’index secondaire global ne peuvent pas extraire d’attributs de la table de base. Par exemple, si vous interrogez `GameTitleIndex` comme illustré dans le diagramme précédent, la requête ne peut pas accéder aux attributs non-clé autres que `TopScore` (même si les attributs de clé `GameTitle` et `UserId` sont automatiquement projetés).
Dans une table DynamoDB, chaque valeur de clé doit être unique. En revanche, les valeurs de clé dans un index secondaire global n’ont pas besoin d’être uniques. À des fins d’illustration, supposons qu’un jeu nommé Comet Quest soit particulièrement difficile, avec de nombreux utilisateurs qui tentent en vain d’obtenir un score supérieur à zéro. Les quelques données suivantes représentent ce comportement.
****
| UserId | GameTitle | TopScore |
| --- | --- | --- |
| 123 | Comet Quest | 0 |
| 201 | Comet Quest | 0 |
| 301 | Comet Quest | 0 |
Lorsque de l’ajout de ces données à la table `GameScores`, DynamoDB les propage vers `GameTitleIndex`. Si nous interrogeons alors l’index à l’aide de Comet Quest pour `GameTitle` et de 0 pour `TopScore`, les données suivantes sont renvoyées.
![\[Table contenant la liste des titres, scores et ID utilisateur.\]](http://docs.aws.amazon.com/fr_fr/amazondynamodb/latest/developerguide/images/GSI_05.png)
Seuls les éléments avec les valeurs de clé spécifiée apparaissent dans la réponse. Au sein de cet ensemble de données, les éléments ne figurent dans aucun ordre particulier.
Un index secondaire global ne suit que les éléments de données où ses attributs clés existent réellement. Par exemple, supposons que vous ayez ajouté un nouvel élément à la table `GameScores`, mais que vous n’ayez fourni que les attributs de clé primaires requis.
****
| UserId | GameTitle |
| --- | --- |
| 400 | Comet Quest |
Étant donné que vous n’avez pas spécifié l’attribut `TopScore`, DynamoDB ne propage pas cet élément vers `GameTitleIndex`. Par conséquent, si vous interrogiez `GameScores` pour tous les éléments Comet Quest, vous obtiendriez les quatre éléments suivants.
![\[Table contenant la liste de 4 titres, des meilleurs scores et des ID utilisateur.\]](http://docs.aws.amazon.com/fr_fr/amazondynamodb/latest/developerguide/images/GSI_04.png)
Une requête similaire sur `GameTitleIndex` renvoie toujours trois éléments, plutôt que quatre. Cela est dû au fait que l’élément avec `TopScore` non existant n’est pas propagé sur l’index.
![\[Table contenant la liste de 3 titres, des meilleurs scores et des ID utilisateur.\]](http://docs.aws.amazon.com/fr_fr/amazondynamodb/latest/developerguide/images/GSI_05.png)
## Projections d’attribut
Une *projection* est l’ensemble d’attributs copié à partir d’une table dans un index secondaire. Les clés de partition et de tri de la table sont toujours projetées dans l’index. Vous pouvez projeter d’autres attributs en fonction des exigences de requête de votre application. Lorsque vous interrogez un index, Amazon DynamoDB peut accéder à n’importe quel attribut dans la projection, comme s’il se trouvait dans une table.
Lorsque vous créez un index secondaire, vous devez spécifier les attributs qui seront projetés dans celui-ci. Pour cela, DynamoDB propose trois options :
+ *KEYS\$1ONLY* – Chaque élément de l’index se compose uniquement des valeurs de clé de partition et de tri de la table, ainsi que des valeurs de clé d’index. L’option `KEYS_ONLY` produit l’index secondaire le plus petit possible.
+ *INCLUDE* – En plus des attributs décrits dans `KEYS_ONLY`, l’index secondaire inclut des attributs autres que de clé, que vous spécifiez.
+ *ALL* – L’index secondaire inclut tous les attributs de la table source. Toutes les données de la table étant dupliquées dans l’index, une projection `ALL` produit l’index secondaire le plus grand possible.
Dans le précédent diagramme, `GameTitleIndex` n’a qu’un seul attribut projeté : `UserId`. Par conséquent, si une application peut déterminer efficacement le `UserId` des joueurs avec les scores les plus élevés pour chaque jeu à l’aide de `GameTitle` et de `TopScore` dans des requêtes, elle peut déterminer efficacement le taux le plus élevé de victoires par rapport au nombre de défaites pour ces joueurs. Pour ce faire, l'application devra effectuer une requête supplémentaire sur la table de base pour récupérer les victoires et les défaites de chacun des meilleurs buteurs. Une façon plus efficace de prendre en charge les requêtes sur ces données serait de projeter ces attributs de la table de base vers l’index secondaire global, comme illustré dans ce diagramme.
![\[Représentation de la projection d’attributs non clés dans un GSI pour permettre une interrogation efficace.\]](http://docs.aws.amazon.com/fr_fr/amazondynamodb/latest/developerguide/images/GSI_06.png)
Comme les attributs non clés `Wins` et`Losses` sont projetés dans l’index, une application peut déterminer le rapport entre le nombre de victoires et le nombre de défaites de n’importe quel jeu, ou pour toute combinaison d’ID d’utilisateur et de jeu.
Lorsque vous choisissez les attributs à projeter sur un index secondaire global, vous devez prendre en compte le compromis entre les coûts de débit approvisionné et les coûts de stockage :
+ Si vous n’avez besoin d’accéder qu’à quelques attributs avec la plus faible latence possible, envisagez de projeter ces seuls attributs dans un index secondaire global. Plus l’index est petit, moins les coûts d’écriture et de stockage sont élevés.
+ Si votre application accède fréquemment à des attributs autres que de clé, vous devez envisager de projeter ceux-ci dans un index secondaire global. Les coûts de stockage supplémentaires de l’index secondaire global compensent le coût d’exécution d’analyses de table fréquentes.
+ Si vous avez besoin d’accéder fréquemment à la plupart des attributs autres que de clé, vous pouvez projeter ceux-ci (voire la table de base toute entière) dans un index secondaire global. Cela vous offre une flexibilité maximale. Cependant, vos coûts de stockage augmenteront, voire doubleront.
+ Si votre application doit interroger peu fréquemment une table, mais doit exécuter un grand nombre d’écritures ou de mises à jour des données de la table, pensez à projeter `KEYS_ONLY`. L’index secondaire global sera d’une taille minimale, mais continuera d’être disponible chaque fois que ce sera nécessaire pour une activité de requête.
## Schéma de clé à attributs multiples
Les index secondaires globaux prennent en charge les clés à attributs multiples, ce qui vous permet de composer des clés de partition et de trier les clés à partir de plusieurs attributs. Avec les clés à attributs multiples, vous pouvez créer une clé de partition à partir de quatre attributs au maximum et une clé de tri à partir de quatre attributs, pour un total de huit attributs par schéma de clé.
Les clés à attributs multiples simplifient votre modèle de données en éliminant le besoin de concaténer manuellement les attributs dans des clés synthétiques. Au lieu de créer des chaînes composites`TOURNAMENT#WINTER2024#REGION#NA-EAST`, vous pouvez utiliser directement les attributs naturels de votre modèle de domaine. DynamoDB gère automatiquement la logique des clés composites, en hachant plusieurs attributs de clé de partition pour la distribution des données et en maintenant un ordre de tri hiérarchique entre plusieurs attributs de clé de tri.
Par exemple, imaginez un système de tournois de jeu dans lequel vous souhaitez organiser les matchs par tournoi et par région. Avec les clés à attributs multiples, vous pouvez définir votre clé de partition sous la forme de deux attributs distincts : `tournamentId` et`region`. De même, vous pouvez définir votre clé de tri à l'aide de plusieurs attributs tels que `round``bracket`, et `matchId` pour créer une hiérarchie naturelle. Cette approche permet de saisir vos données et de garder votre code propre, sans manipulation de chaînes ni analyse syntaxique.
Lorsque vous interrogez un index secondaire global avec des clés à attributs multiples, vous devez spécifier tous les attributs de clé de partition en utilisant des conditions d'égalité. Pour trier les attributs clés, vous pouvez les interroger left-to-right dans l'ordre dans lequel ils sont définis dans le schéma de clé. Cela signifie que vous pouvez interroger le premier attribut clé de tri seul, les deux premiers attributs ensemble ou tous les attributs ensemble, mais vous ne pouvez pas ignorer les attributs situés au milieu. Les conditions d'inégalité telles que `>` `<``BETWEEN`,, ou `begins_with()` doivent être la dernière condition de votre requête.
Les clés à attributs multiples fonctionnent particulièrement bien lors de la création d'index secondaires globaux sur des tables existantes. Vous pouvez utiliser des attributs qui existent déjà dans votre table sans avoir à ajouter des clés synthétiques à vos données. Cela permet d'ajouter facilement de nouveaux modèles de requête à votre application en créant des index qui réorganisent vos données à l'aide de différentes combinaisons d'attributs.
Chaque attribut d'une clé à attributs multiples peut avoir son propre type de données : `String` (S), `Number` (N) ou `Binary` (B). Lorsque vous choisissez des types de données, considérez que `Number` les attributs sont triés numériquement sans nécessiter de remplissage nul, tandis que les `String` attributs sont triés de manière lexicographique. Par exemple, si vous utilisez un `Number` type pour un attribut de score, les valeurs 5, 50, 500 et 1000 sont triées par ordre numérique naturel. Les mêmes valeurs que le `String` type seront triées comme « 1000 », « 5 », « 50 », « 500 », sauf si vous les complétez avec des zéros en tête.
Lorsque vous concevez des clés à attributs multiples, classez vos attributs du plus général au plus spécifique. Pour les clés de partition, combinez les attributs qui sont toujours interrogés ensemble et qui assurent une bonne distribution des données. Pour les clés de tri, placez les attributs fréquemment demandés en premier dans la hiérarchie afin d'optimiser la flexibilité des requêtes. Cet ordre vous permet d'effectuer des requêtes à n'importe quel niveau de granularité correspondant à vos habitudes d'accès.
Consultez le [Clés à attributs multiples](GSI.DesignPattern.MultiAttributeKeys.md) pour des exemples de mise en œuvre.
## Lecture de données à partir d’un index secondaire global
Vous pouvez extraire des éléments d’un index secondaire global à l’aide des opérations `Query` et `Scan`. Vous ne pouvez pas utiliser les opérations `GetItem` et `BatchGetItem` sur un index secondaire global.
### Interrogation d’un index secondaire global
Vous pouvez utiliser l’opération `Query` pour accéder à un ou plusieurs éléments dans un index secondaire global. La requête doit spécifier le nom de la table de base et le nom de l’index que vous souhaitez utiliser, les attributs à renvoyer dans les résultats de la requête, ainsi que toutes les conditions de requête que vous souhaitez appliquer. DynamoDB peut renvoyer les résultats dans l’ordre croissant ou décroissant.
Prenez en compte les données suivantes retournées à partir d’une opération `Query` qui demande les données de jeu pour une application de classement.
```
{
"TableName": "GameScores",
"IndexName": "GameTitleIndex",
"KeyConditionExpression": "GameTitle = :v_title",
"ExpressionAttributeValues": {
":v_title": {"S": "Meteor Blasters"}
},
"ProjectionExpression": "UserId, TopScore",
"ScanIndexForward": false
}
```
Dans cette requête :
+ DynamoDB y *GameTitleIndex*accède à l'aide de la clé de partition pour localiser *GameTitle*les éléments d'index des Meteor Blasters. Tous les éléments d’index avec cette clé sont stockés les uns à côté des autres pour une récupération rapide.
+ Dans ce jeu, DynamoDB utilise l'index pour accéder à tous les IDs utilisateurs et aux meilleurs scores de ce jeu.
+ Les résultats sont retournés, triés par ordre décroissant, car le paramètre `ScanIndexForward` a la valeur false.
### Interrogation d’un index secondaire global
Vous pouvez utiliser l’opération `Scan` pour extraire toutes les données d’un index secondaire global. Vous devez fournir le nom de la table de base et le nom de l’index dans la demande. Avec une opération `Scan`, DynamoDB lit toutes les données de l’index et les renvoie à l’application. Vous pouvez également demander que seules quelques données soient retournées, et que les données restantes soient ignorées. Pour ce faire, utilisez le paramètre `FilterExpression` de l’opération `Scan`. Pour de plus amples informations, veuillez consulter [Filtrer les expressions à des fins d’analyse](Scan.md#Scan.FilterExpression).
## Synchronisation des données entre les tables et les index secondaires globaux
DynamoDB synchronise automatiquement chaque index secondaire global avec sa table de base. Quand une application écrit ou supprime des éléments dans une table, tout index secondaire global sur cette table est mis à jour de manière asynchrone, à l’aide d’un modèle éventuellement cohérent. Les applications n’écrivent jamais directement sur un index. Cependant, il est important de comprendre les implications de la façon dont DynamoDB gère ces index.
Les index secondaires globaux héritent du mode read/write capacité de la table de base. Pour de plus amples informations, veuillez consulter [Considérations relatives au changement de mode de capacité dans DynamoDB](bp-switching-capacity-modes.md).
Lorsque vous créez un index secondaire global, vous spécifiez un ou plusieurs attributs de clé d’index et leurs types de données. Cela signifie que chaque fois que vous écrivez un élément sur la table de base, les types de données de ces attributs doivent correspondre aux types de données du schéma de la clé d’index. Dans le cas de `GameTitleIndex`, la clé de partition `GameTitle` de l’index est définie comme type de données `String`. La clé de tri `TopScore` de l’index est de type `Number`. Si vous essayez d’ajouter un élément à la table `GameScores` et spécifiez un type de données différent pour `GameTitle` ou pour `TopScore`, DynamoDB renvoie une `ValidationException` en raison de la discordance des types de données.
Lorsque vous insérez ou supprimez des éléments dans une table, les index secondaires globaux sont mis à jour selon une façon éventuellement cohérente. Les modifications apportées aux données de la table sont propagées sur les index secondaires globaux en une fraction de seconde, dans des conditions normales. Cependant, dans certains scénarios de défaillance peu probables, les retards de propagation peuvent être plus longs. Pour cette raison, vos applications ont besoin d’anticiper et de gérer les situations où une requête sur un index secondaire global renvoie des résultats qui ne sont pas à jour.
Si vous écrivez un élément dans une table, vous n’avez pas à spécifier les attributs pour une clé de tri d’index secondaire global. Si vous utilisez `GameTitleIndex` comme exemple, vous n’avez pas besoin de spécifier une valeur pour l’attribut `TopScore` pour pouvoir écrire un nouvel élément sur la table `GameScores`. Dans ce cas, DynamoDB n’écrit aucune donnée dans l’index pour cet élément particulier.
Une table avec de nombreux index secondaires globaux s’expose à des coûts plus élevés pour l’activité d’écriture qu’une table ayant moins d’index. Pour de plus amples informations, veuillez consulter [Considérations sur le débit alloué pour les index secondaires globaux](#GSI.ThroughputConsiderations).
## Classes de tables avec index secondaire global
Un index secondaire global utilisera toujours la même classe de tables que sa table de base. Chaque fois qu’un nouvel index secondaire global est ajouté à une table, le nouvel index utilise la même classe de tables que sa table de base. Lorsque la classe de tables d’une table est mise à jour, tous les index secondaires globaux associés sont également mis à jour.
## Considérations sur le débit alloué pour les index secondaires globaux
Lorsque vous créez un index secondaire global sur une table en mode approvisionné, vous devez spécifier des unités de capacité de lecture et d’écriture pour la charge de travail prévue sur cet index. Les paramètres de débit approvisionné d’un index secondaire global sont distincts de ceux de sa table de base. Une opération `Query` sur un index secondaire global consomme les unités de capacité de lecture de l’index, pas de la table de base. Lorsque vous insérez ou supprimez des éléments dans une table, les index secondaires globaux sont également mis à jour. Ces mises à jour d’index consomment des unités de capacité d’écriture à partir de l’index, et non à partir de la table de base.
Par exemple, si vous exécutez une opération `Query` sur un index secondaire global et dépassez sa capacité de lecture approvisionnée, votre demande est limitée. Si vous exécutez une activité d’écriture massive sur la table, alors qu’un index secondaire global sur celle-ci a une capacité d’écriture insuffisante, l’activité d’écriture sur la table est limitée.
**Important**
Pour éviter les limitations potentielles, la capacité d’écriture allouée pour un index secondaire global doit être supérieure ou égale à la capacité d’écriture de la table de base, car les nouvelles mises à jour écrivent dans la table de base et l’index secondaire global.
Afin de modifier les paramètres de débit approvisionné pour un index secondaire global, utilisez l’opération `DescribeTable`. Des informations détaillées sur tous les index secondaires globaux de la table sont retournées.
### Unités de capacité de lecture
Les index secondaires globaux prennent en charge les lectures éventuellement cohérentes ; chacune d’elles utilise la moitié d’une unité de capacité en lecture. Cela signifie qu’une interrogation d’index secondaire global peut extraire jusqu’à 2 x 4 Ko = 8 Ko par unité de capacité de lecture.
Pour les interrogations d’index secondaire global, DynamoDB calcule l’activité de lecture approvisionnée de la même façon que pour les interrogations de tables. La seule différence est que le calcul est basé sur les tailles des entrées d’index, plutôt que sur la taille de l’élément de la table de base. Le nombre d’unités de capacité en lecture est la somme des tailles de tous les attributs projetés de tous les éléments renvoyés. Le résultat est ensuite arrondi à la limite de 4 Ko suivante. Pour plus d’informations sur la façon dont DynamoDB calcule l’utilisation du débit approvisionné, consultez [Mode de capacité provisionnée DynamoDB](provisioned-capacity-mode.md).
La taille maximum des résultats renvoyés par une opération `Query` est de 1 Mo. Cela inclut les tailles de tous les noms et valeurs d’attribut à travers l’ensemble des éléments retournés.
Par exemple, considérons un index secondaire global où chaque élément contient 2 000 octets de données. Supposons à présent que vous effectuez une opération `Query` sur cet index et que la `KeyConditionExpression` de la requête renvoie huit éléments. La taille totale des éléments correspondants est de 2 000 octets x 8 éléments = 16 000 octets. Ce résultat est ensuite arrondi à la limite de 4 Ko la plus proche. Les interrogations d’index secondaire global étant éventuellement cohérentes, le coût total est de 0,5 x (16 Ko / 4 Ko), soit 2 unités de capacité de lecture.
### Unités de capacité d’écriture
Lors de l’ajout, de la mise à jour ou de la suppression d’un élément dans une table, si l’opération affecte un index secondaire global, celui-ci consomme les unités de capacité d’écriture approvisionnée à cette fin. Le coût total du débit alloué pour une écriture se compose de la somme des unités de capacité en écriture utilisées par l’écriture sur la table de base et de celles utilisées par la mise à jour des index secondaires globaux. Notez que, si une écriture dans une table ne requiert de mise à jour d’index secondaire global, aucune capacité d’écriture n’est consommée à partir de l’index.
Pour qu’une écriture de table réussisse, les paramètres de débit provisionnés de la table et de tous ses index secondaires globaux doivent avoir une capacité d’écriture suffisante pour accueillir l’écriture. Sinon, l’écriture dans la table est limitée.
**Important**
Lors de la création d’un index secondaire global (GSI), les opérations d’écriture dans la table de base peuvent être limitées si l’activité GSI résultant des écritures dans la table de base dépasse la capacité d’écriture allouée au GSI. Cette limitation affecte toutes les opérations d’écriture, du processus d’indexation à la perturbation potentielle de vos charges de travail de production. Pour plus d’informations, consultez [Résolution des problèmes de limitation dans Amazon DynamoDB](https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/TroubleshootingThrottling.html).
Le coût d’écriture d’un élément dans un index secondaire global dépend de plusieurs facteurs :
+ Si vous écrivez un nouvel élément sur la table qui définit un attribut indexé, ou que vous mettez à jour un élément existant pour définir un attribut indexé précédemment non défini, une opération d’écriture est nécessaire pour insérer l’élément dans l’index.
+ Si une mise à jour de la table change la valeur d’un attribut de clé indexée (de A en B), deux écritures sont requises, une pour supprimer l’élément précédent de l’index et une autre pour insérer le nouveau élément dans l’index.
+ Si un élément était présent dans l’index, mais qu’une écriture sur la table a entraîné la suppression de l’attribut indexé, une écriture est nécessaire pour supprimer de l’index la projection de l’ancien élément.
+ Si un élément n’est pas présent dans l’index avant ou après la mise à jour de l’élément, il n’y a aucun coût d’écriture supplémentaire pour l’index.
+ Si la mise à jour de la table ne modifie que la valeur des attributs projetés du schéma de clé d’index, mais ne change pas la valeur d’un quelconque attribut de clé indexé, une écriture est nécessaire pour mettre à jour les valeurs des attributs projetés sur l’index.
Tous ces facteurs partent du principe que la taille de chaque élément dans l’index est inférieure ou égale à la taille d’élément de 1 Ko pour le calcul des unités de capacité d’écriture. Les plus grandes entrées d’index nécessitent des unités de capacité en écriture supplémentaires. Vous pouvez réduire vos coûts d’écriture en considérant les attributs que vos requêtes ont besoin de retourner et en projetant uniquement ces attributs dans l’index.
## Considérations relatives au stockage pour les index secondaires globaux
Quand une application écrit un élément dans une table, DynamoDB copie automatiquement le sous-ensemble approprié d’attributs vers les index secondaires globaux où ces attributs doivent apparaître. Votre AWS compte est débité pour le stockage de l'article dans la table de base ainsi que pour le stockage des attributs dans les index secondaires globaux de cette table.
La quantité d’espace utilisée par un élément de l’index est la somme des éléments suivants :
+ La taille en octets de la clé primaire de la table de base (clé de partition et clé de tri)
+ La taille en octets de l’attribut de clé d’index
+ La taille en octets des attributs projetés (le cas échéant)
+ 100 octets de surcharge par élément d’index
Afin d’estimer les exigences de stockage pour un index secondaire global, vous pouvez évaluer la taille moyenne d’un élément de l’index, puis la multiplier par le nombre d’éléments de la table de base ayant les attributs de clé d’index secondaire global.
Si une table contient un élément dont aucun attribut particulier n'est défini, mais que cet attribut est défini comme clé de partition d'index ou clé de tri, DynamoDB n'écrit aucune donnée pour cet élément dans l'index.
# Motifs de design
Les modèles de conception fournissent des solutions éprouvées aux défis courants liés à l'utilisation d'index secondaires globaux. Ces modèles vous aident à créer des applications efficaces et évolutives en vous montrant comment structurer vos index pour des cas d'utilisation spécifiques.
Chaque modèle inclut un guide d'implémentation complet avec des exemples de code, les meilleures pratiques et des cas d'utilisation réels pour vous aider à appliquer le modèle à vos propres applications.
**Topics**
+ [Clés à attributs multiples](GSI.DesignPattern.MultiAttributeKeys.md)
# Modèle de clés à attributs multiples
## Aperçu
Les clés à attributs multiples vous permettent de créer une partition d'index secondaire global (GSI) et de trier les clés composées d'un maximum de quatre attributs chacune. Cela réduit le code côté client et facilite la modélisation initiale des données et l'ajout de nouveaux modèles d'accès ultérieurement.
Imaginons un scénario courant : pour créer un GSI qui interroge des éléments selon plusieurs attributs hiérarchiques, vous devez traditionnellement créer des clés synthétiques en concaténant des valeurs. Par exemple, dans une application de jeu, pour interroger les matchs d'un tournoi par tournoi, région et manche, vous pouvez créer une clé de partition GSI synthétique telle que TOURNAMENT\$1 WINTER2 024 \$1REGION \$1NA -EAST et une clé de tri synthétique telle que ROUND \$1SEMIFINALS \$1BRACKET \$1UPPER. Cette approche fonctionne, mais nécessite la concaténation de chaînes lors de l'écriture de données, l'analyse lors de la lecture et le remplissage de clés synthétiques sur tous les éléments existants si vous ajoutez le GSI à une table existante. Cela rend le code plus encombré et il est difficile de maintenir la sécurité des types sur les composants clés individuels.
Les clés à attributs multiples résolvent ce problème pour GSIs. Vous définissez votre clé de partition GSI à l'aide de plusieurs attributs existants tels que TournamentID et region. DynamoDB gère automatiquement la logique des clés composites, en les hachant ensemble pour la distribution des données. Vous écrivez des éléments en utilisant les attributs naturels de votre modèle de domaine, et le GSI les indexe automatiquement. Pas de concaténation, pas d'analyse syntaxique, pas de remblayage. Votre code reste propre, vos données restent saisies et vos requêtes restent simples. Cette approche est particulièrement utile lorsque vous disposez de données hiérarchiques avec des groupements d'attributs naturels (par exemple tournoi → région → manche, ou organisation → département → équipe).
## Exemple d'application
Ce guide explique comment créer un système de suivi des matchs de tournoi pour une plateforme d'e-sport. La plateforme doit interroger efficacement les matchs selon plusieurs critères : par tournoi et par région pour la gestion des brackets, par joueur pour l'historique des matchs et par date pour la programmation.
## Modèle de données
Dans cette présentation, le système de suivi des matchs de tournoi prend en charge trois modèles d'accès principaux, chacun nécessitant une structure de clé différente :
**Modèle d'accès 1 :** recherchez une correspondance spécifique à l'aide de son identifiant unique
+ **Solution :** table de base avec `matchId` comme clé de partition
**Modèle d'accès 2 :** recherchez tous les matchs pour un tournoi et une région spécifiques, en filtrant éventuellement par tour, bracket ou match
+ **Solution :** index secondaire global avec clé de partition multi-attributs (`tournamentId`\$1`region`) et clé de tri multi-attributs (`round`\$1 \$1`bracket`) `matchId`
+ **Exemples de requêtes :** « Tous les WINTER2 024 matchs dans la région NA-EAST » ou « Tous les matchs des DEMI-FINALES dans la tranche SUPÉRIEURE pour 024/NA-EAST » WINTER2
**Modèle d'accès 3 : recherchez** l'historique des matchs d'un joueur, en filtrant éventuellement par plage de dates ou par tour de tournoi
+ **Solution :** index secondaire global avec clé de partition unique (`player1Id`) et clé de tri multi-attributs (`matchDate`\$1`round`)
+ **Exemples de requêtes :** « Tous les matchs du joueur 101 » ou « Les matchs du joueur 101 en janvier 2024 »
La principale différence entre les approches traditionnelles et les approches à attributs multiples apparaît clairement lorsque l'on examine la structure des articles :
**Approche traditionnelle de l'index secondaire global (clés concaténées) :**
```
// Manual concatenation required for GSI keys
const item = {
matchId: 'match-001', // Base table PK
tournamentId: 'WINTER2024',
region: 'NA-EAST',
round: 'SEMIFINALS',
bracket: 'UPPER',
player1Id: '101',
// Synthetic keys needed for GSI
GSI_PK: `TOURNAMENT#${tournamentId}#REGION#${region}`, // Must concatenate
GSI_SK: `${round}#${bracket}#${matchId}`, // Must concatenate
// ... other attributes
};
```
**Approche de l'index secondaire global à attributs multiples (clés natives) :**
```
// Use existing attributes directly - no concatenation needed
const item = {
matchId: 'match-001', // Base table PK
tournamentId: 'WINTER2024',
region: 'NA-EAST',
round: 'SEMIFINALS',
bracket: 'UPPER',
player1Id: '101',
matchDate: '2024-01-18',
// No synthetic keys needed - GSI uses existing attributes directly
// ... other attributes
};
```
Avec les clés à attributs multiples, vous pouvez écrire des éléments une seule fois avec des attributs de domaine naturels. DynamoDB les indexe automatiquement sur GSIs plusieurs sans nécessiter de clés concaténées synthétiques.
**Schéma de table de base :**
+ Clé de partition : `matchId` (1 attribut)
**Schéma d'index secondaire global (TournamentRegionIndex avec clés à attributs multiples) :**
+ Clé de partition :`tournamentId`, `region` (2 attributs)
+ Clé de tri : `round``bracket`,, `matchId` (3 attributs)
**Schéma d'index secondaire global (PlayerMatchHistoryIndex avec clés à attributs multiples) :**
+ Clé de partition : `player1Id` (1 attribut)
+ Clé de tri :`matchDate`, `round` (2 attributs)
### Table de base : TournamentMatches
| MatchID (PK) | ID du tournoi | region | round | crochet | ID du joueur 1 | ID du joueur 2 | Date du match | vainqueur | score |
| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- |
| match-001 | WINTER2024 | NA-EAST | FINALES | CHAMPIONNAT | 101 | 103 | 20-01-2024 | 101 | 3-1 |
| match-002 | WINTER2024 | NA-EAST | DEMI-FINALES | UPPER | 101 | 105 | 18-01-2024 | 101 | 3-2 |
| match-003 | WINTER2024 | NA-EAST | DEMI-FINALES | UPPER | 103 | 107 | 18-01-2024 | 103 | 3-0 |
| match-004 | WINTER2024 | NA-EAST | QUARTS DE FINALE | UPPER | 101 | 109 | 15-01-2024 | 101 | 3-1 |
| match-005 | WINTER2024 | NA-WEST | FINALES | CHAMPIONNAT | 102 | 104 | 20-01-2024 | 102 | 3-2 |
| match-006 | WINTER2024 | NA-WEST | DEMI-FINALES | UPPER | 102 | 106 | 18-01-2024 | 102 | 3-1 |
| match-007 | SPRING2024 | NA-EAST | QUARTS DE FINALE | UPPER | 101 | 108 | 15/03/2024 | 101 | 3-0 |
| match-008 | SPRING2024 | NA-EAST | QUARTS DE FINALE | LOWER | 103 | 110 | 15/03/2024 | 103 | 3-2 |
### GSI : TournamentRegionIndex (clés à attributs multiples)
| ID du tournoi (PK) | région (PK) | rond (SK) | support (SK) | MatchID (SK) | ID du joueur 1 | ID du joueur 2 | Date du match | vainqueur | score |
| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- |
| WINTER2024 | NA-EAST | FINALES | CHAMPIONNAT | match-001 | 101 | 103 | 20-01-2024 | 101 | 3-1 |
| WINTER2024 | NA-EAST | QUARTS DE FINALE | UPPER | match-004 | 101 | 109 | 15-01-2024 | 101 | 3-1 |
| WINTER2024 | NA-EAST | DEMI-FINALES | UPPER | match-002 | 101 | 105 | 18-01-2024 | 101 | 3-2 |
| WINTER2024 | NA-EAST | DEMI-FINALES | UPPER | match-003 | 103 | 107 | 18-01-2024 | 103 | 3-0 |
| WINTER2024 | NA-WEST | FINALES | CHAMPIONNAT | match-005 | 102 | 104 | 20-01-2024 | 102 | 3-2 |
| WINTER2024 | NA-WEST | DEMI-FINALES | UPPER | match-006 | 102 | 106 | 18-01-2024 | 102 | 3-1 |
| SPRING2024 | NA-EAST | QUARTS DE FINALE | LOWER | match-008 | 103 | 110 | 15/03/2024 | 103 | 3-2 |
| SPRING2024 | NA-EAST | QUARTS DE FINALE | UPPER | match-007 | 101 | 108 | 15/03/2024 | 101 | 3-0 |
### GSI : PlayerMatchHistoryIndex (clés à attributs multiples)
| ID du joueur 1 (PK) | MatchDate (SK) | rond (SK) | ID du tournoi | region | crochet | Identifiant du match | ID du joueur 2 | vainqueur | score |
| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- |
| 101 | 15-01-2024 | QUARTS DE FINALE | WINTER2024 | NA-EAST | UPPER | match-004 | 109 | 101 | 3-1 |
| 101 | 18-01-2024 | DEMI-FINALES | WINTER2024 | NA-EAST | UPPER | match-002 | 105 | 101 | 3-2 |
| 101 | 20-01-2024 | FINALES | WINTER2024 | NA-EAST | CHAMPIONNAT | match-001 | 103 | 101 | 3-1 |
| 101 | 15/03/2024 | QUARTS DE FINALE | SPRING2024 | NA-EAST | UPPER | match-007 | 108 | 101 | 3-0 |
| 102 | 18-01-2024 | DEMI-FINALES | WINTER2024 | NA-WEST | UPPER | match-006 | 106 | 102 | 3-1 |
| 102 | 20-01-2024 | FINALES | WINTER2024 | NA-WEST | CHAMPIONNAT | match-005 | 104 | 102 | 3-2 |
| 103 | 18-01-2024 | DEMI-FINALES | WINTER2024 | NA-EAST | UPPER | match-003 | 107 | 103 | 3-0 |
| 103 | 15/03/2024 | QUARTS DE FINALE | SPRING2024 | NA-EAST | LOWER | match-008 | 110 | 103 | 3-2 |
## Prérequis
Avant de commencer, assurez-vous de disposer des éléments suivants :
### Compte et autorisations
+ Un AWS compte actif ([créez-en un ici](https://aws.amazon.com/free/) si nécessaire)
+ Autorisations IAM pour les opérations DynamoDB :
+ `dynamodb:CreateTable`
+ `dynamodb:DeleteTable`
+ `dynamodb:DescribeTable`
+ `dynamodb:PutItem`
+ `dynamodb:Query`
+ `dynamodb:BatchWriteItem`
**Note**
**Note de sécurité :** Pour une utilisation en production, créez une politique IAM personnalisée avec uniquement les autorisations dont vous avez besoin. Pour ce didacticiel, vous pouvez utiliser la politique AWS gérée`AmazonDynamoDBFullAccessV2`.
### Environnement de développement
+ Node.js installé sur votre machine
+ AWS informations d'identification configurées à l'aide de l'une des méthodes suivantes :
**Option 1 : AWS CLI**
```
aws configure
```
**Option 2 : variables d’environnement**
```
export AWS_ACCESS_KEY_ID=your_access_key_here
export AWS_SECRET_ACCESS_KEY=your_secret_key_here
export AWS_DEFAULT_REGION=us-east-1
```
### Installation des packages obligatoires
```
npm install @aws-sdk/client-dynamodb @aws-sdk/lib-dynamodb
```
## Mise en œuvre
### Étape 1 : Création d'une table à GSIs l'aide de clés à attributs multiples
Créez une table avec une structure de clés de base simple et utilisant GSIs des clés à attributs multiples.
#### Exemple de code
```
import { DynamoDBClient, CreateTableCommand } from "@aws-sdk/client-dynamodb";
const client = new DynamoDBClient({ region: 'us-west-2' });
const response = await client.send(new CreateTableCommand({
TableName: 'TournamentMatches',
// Base table: Simple partition key
KeySchema: [
{ AttributeName: 'matchId', KeyType: 'HASH' } // Simple PK
],
AttributeDefinitions: [
{ AttributeName: 'matchId', AttributeType: 'S' },
{ AttributeName: 'tournamentId', AttributeType: 'S' },
{ AttributeName: 'region', AttributeType: 'S' },
{ AttributeName: 'round', AttributeType: 'S' },
{ AttributeName: 'bracket', AttributeType: 'S' },
{ AttributeName: 'player1Id', AttributeType: 'S' },
{ AttributeName: 'matchDate', AttributeType: 'S' }
],
// GSIs with multi-attribute keys
GlobalSecondaryIndexes: [
{
IndexName: 'TournamentRegionIndex',
KeySchema: [
{ AttributeName: 'tournamentId', KeyType: 'HASH' }, // GSI PK attribute 1
{ AttributeName: 'region', KeyType: 'HASH' }, // GSI PK attribute 2
{ AttributeName: 'round', KeyType: 'RANGE' }, // GSI SK attribute 1
{ AttributeName: 'bracket', KeyType: 'RANGE' }, // GSI SK attribute 2
{ AttributeName: 'matchId', KeyType: 'RANGE' } // GSI SK attribute 3
],
Projection: { ProjectionType: 'ALL' }
},
{
IndexName: 'PlayerMatchHistoryIndex',
KeySchema: [
{ AttributeName: 'player1Id', KeyType: 'HASH' }, // GSI PK
{ AttributeName: 'matchDate', KeyType: 'RANGE' }, // GSI SK attribute 1
{ AttributeName: 'round', KeyType: 'RANGE' } // GSI SK attribute 2
],
Projection: { ProjectionType: 'ALL' }
}
],
BillingMode: 'PAY_PER_REQUEST'
}));
console.log("Table with multi-attribute GSI keys created successfully");
```
**Principales décisions de conception :**
**Table de base :** La table de base utilise une clé de `matchId` partition simple pour les recherches par correspondance directe, ce qui permet de maintenir la structure de la table de base simple tout en GSIs fournissant des modèles de requête complexes.
**TournamentRegionIndex Index secondaire global : L'index** secondaire `TournamentRegionIndex` mondial utilise `tournamentId` \$1 `region` comme clé de partition à attributs multiples, ce qui crée une isolation entre les régions de tournois, les données étant distribuées par le hachage des deux attributs combinés, ce qui permet d'effectuer des requêtes efficaces dans un contexte de région de tournoi spécifique. La clé de tri à attributs multiples (`round`\$1 `bracket` \$1`matchId`) permet un tri hiérarchique qui prend en charge les requêtes à tous les niveaux de la hiérarchie avec un ordre naturel, du général (rond) au spécifique (identifiant de correspondance).
**PlayerMatchHistoryIndex Index secondaire mondial : L'index** secondaire `PlayerMatchHistoryIndex` mondial réorganise les données par joueur en les utilisant `player1Id` comme clé de partition, ce qui permet d'effectuer des requêtes entre tournois pour un joueur spécifique. La clé de tri à attributs multiples (`matchDate`\$1`round`) fournit un ordre chronologique avec la possibilité de filtrer par plages de dates ou par tours de tournoi spécifiques.
### Étape 2 : Insérer des données avec des attributs natifs
Ajoutez les données des matchs du tournoi à l'aide d'attributs naturels. Le GSI indexera automatiquement ces attributs sans nécessiter de clés synthétiques.
#### Exemple de code
```
import { DynamoDBClient } from "@aws-sdk/client-dynamodb";
import { DynamoDBDocumentClient, PutCommand } from "@aws-sdk/lib-dynamodb";
const client = new DynamoDBClient({ region: 'us-west-2' });
const docClient = DynamoDBDocumentClient.from(client);
// Tournament match data - no synthetic keys needed for GSIs
const matches = [
// Winter 2024 Tournament, NA-EAST region
{
matchId: 'match-001',
tournamentId: 'WINTER2024',
region: 'NA-EAST',
round: 'FINALS',
bracket: 'CHAMPIONSHIP',
player1Id: '101',
player2Id: '103',
matchDate: '2024-01-20',
winner: '101',
score: '3-1'
},
{
matchId: 'match-002',
tournamentId: 'WINTER2024',
region: 'NA-EAST',
round: 'SEMIFINALS',
bracket: 'UPPER',
player1Id: '101',
player2Id: '105',
matchDate: '2024-01-18',
winner: '101',
score: '3-2'
},
{
matchId: 'match-003',
tournamentId: 'WINTER2024',
region: 'NA-EAST',
round: 'SEMIFINALS',
bracket: 'UPPER',
player1Id: '103',
player2Id: '107',
matchDate: '2024-01-18',
winner: '103',
score: '3-0'
},
{
matchId: 'match-004',
tournamentId: 'WINTER2024',
region: 'NA-EAST',
round: 'QUARTERFINALS',
bracket: 'UPPER',
player1Id: '101',
player2Id: '109',
matchDate: '2024-01-15',
winner: '101',
score: '3-1'
},
// Winter 2024 Tournament, NA-WEST region
{
matchId: 'match-005',
tournamentId: 'WINTER2024',
region: 'NA-WEST',
round: 'FINALS',
bracket: 'CHAMPIONSHIP',
player1Id: '102',
player2Id: '104',
matchDate: '2024-01-20',
winner: '102',
score: '3-2'
},
{
matchId: 'match-006',
tournamentId: 'WINTER2024',
region: 'NA-WEST',
round: 'SEMIFINALS',
bracket: 'UPPER',
player1Id: '102',
player2Id: '106',
matchDate: '2024-01-18',
winner: '102',
score: '3-1'
},
// Spring 2024 Tournament, NA-EAST region
{
matchId: 'match-007',
tournamentId: 'SPRING2024',
region: 'NA-EAST',
round: 'QUARTERFINALS',
bracket: 'UPPER',
player1Id: '101',
player2Id: '108',
matchDate: '2024-03-15',
winner: '101',
score: '3-0'
},
{
matchId: 'match-008',
tournamentId: 'SPRING2024',
region: 'NA-EAST',
round: 'QUARTERFINALS',
bracket: 'LOWER',
player1Id: '103',
player2Id: '110',
matchDate: '2024-03-15',
winner: '103',
score: '3-2'
}
];
// Insert all matches
for (const match of matches) {
await docClient.send(new PutCommand({
TableName: 'TournamentMatches',
Item: match
}));
console.log(`Added: ${match.matchId} - ${match.tournamentId}/${match.region} - ${match.round} ${match.bracket}`);
}
console.log(`\nInserted ${matches.length} tournament matches`);
console.log("No synthetic keys created - GSIs use native attributes automatically");
```
**Structure des données expliquée :**
**Utilisation naturelle des attributs :** chaque attribut représente un véritable concept de tournoi sans aucune concaténation ou analyse de chaînes requise, fournissant ainsi un mappage direct avec le modèle de domaine.
Indexation **automatique de l'index secondaire global : Indexation** GSIs automatique des éléments à l'aide des attributs existants (`tournamentId``region`,`round`,`bracket`, `matchId` pour TournamentRegionIndex et `player1Id``matchDate`, `round` pour PlayerMatchHistoryIndex) sans nécessiter de clés concaténées synthétiques.
**Aucun remplissage supplémentaire n'est nécessaire :** lorsque vous ajoutez un nouvel index secondaire global avec des clés à attributs multiples à une table existante, DynamoDB indexe automatiquement tous les éléments existants à l'aide de leurs attributs naturels. Il n'est pas nécessaire de mettre à jour les éléments à l'aide de clés synthétiques.
### Étape 3 : Interrogez TournamentRegionIndex l'index secondaire global avec tous les attributs de clé de partition
Cet exemple interroge l'index secondaire TournamentRegionIndex global qui possède une clé de partition à attributs multiples (`tournamentId`\$1`region`). Tous les attributs de clé de partition doivent être spécifiés avec des conditions d'égalité dans les requêtes. Vous ne pouvez pas effectuer de requête `tournamentId` uniquement ou utiliser des opérateurs d'inégalité sur les attributs de clé de partition.
#### Exemple de code
```
import { DynamoDBClient } from "@aws-sdk/client-dynamodb";
import { DynamoDBDocumentClient, QueryCommand } from "@aws-sdk/lib-dynamodb";
const client = new DynamoDBClient({ region: 'us-west-2' });
const docClient = DynamoDBDocumentClient.from(client);
// Query GSI: All matches for WINTER2024 tournament in NA-EAST region
const response = await docClient.send(new QueryCommand({
TableName: 'TournamentMatches',
IndexName: 'TournamentRegionIndex',
KeyConditionExpression: 'tournamentId = :tournament AND #region = :region',
ExpressionAttributeNames: {
'#region': 'region', // 'region' is a reserved keyword
'#tournament': 'tournament'
},
ExpressionAttributeValues: {
':tournament': 'WINTER2024',
':region': 'NA-EAST'
}
}));
console.log(`Found ${response.Items.length} matches for WINTER2024/NA-EAST:\n`);
response.Items.forEach(match => {
console.log(` ${match.round} | ${match.bracket} | ${match.matchId}`);
console.log(` Players: ${match.player1Id} vs ${match.player2Id}`);
console.log(` Winner: ${match.winner}, Score: ${match.score}\n`);
});
```
**Résultat attendu :**
```
Found 4 matches for WINTER2024/NA-EAST:
FINALS | CHAMPIONSHIP | match-001
Players: 101 vs 103
Winner: 101, Score: 3-1
QUARTERFINALS | UPPER | match-004
Players: 101 vs 109
Winner: 101, Score: 3-1
SEMIFINALS | UPPER | match-002
Players: 101 vs 105
Winner: 101, Score: 3-2
SEMIFINALS | UPPER | match-003
Players: 103 vs 107
Winner: 103, Score: 3-0
```
**Requêtes non valides :**
```
// Missing region attribute
KeyConditionExpression: 'tournamentId = :tournament'
// Using inequality on partition key attribute
KeyConditionExpression: 'tournamentId = :tournament AND #region > :region'
```
**Performances :** les clés de partition à attributs multiples sont hachées ensemble, offrant les mêmes performances de recherche O (1) que les clés à attribut unique.
### Étape 4 : demander les clés de tri de l'index secondaire global left-to-right
Les attributs clés de tri doivent être interrogés left-to-right dans l'ordre dans lequel ils sont définis dans l'index secondaire global. Cet exemple montre comment interroger les différents TournamentRegionIndex niveaux hiérarchiques : filtrage par simple`round`, par `round` \$1 `bracket` ou par les trois attributs clés de tri. Vous ne pouvez pas ignorer les attributs au milieu. Par exemple, vous ne pouvez pas effectuer d'interrogation par `round` et `matchId` pendant les sauts. `bracket`
#### Exemple de code
```
import { DynamoDBClient } from "@aws-sdk/client-dynamodb";
import { DynamoDBDocumentClient, QueryCommand } from "@aws-sdk/lib-dynamodb";
const client = new DynamoDBClient({ region: 'us-west-2' });
const docClient = DynamoDBDocumentClient.from(client);
// Query 1: Filter by first sort key attribute (round)
console.log("Query 1: All SEMIFINALS matches");
const query1 = await docClient.send(new QueryCommand({
TableName: 'TournamentMatches',
IndexName: 'TournamentRegionIndex',
KeyConditionExpression: 'tournamentId = :tournament AND #region = :region AND round = :round',
ExpressionAttributeNames: {
'#region': 'region' // 'region' is a reserved keyword
},
ExpressionAttributeValues: {
':tournament': 'WINTER2024',
':region': 'NA-EAST',
':round': 'SEMIFINALS'
}
}));
console.log(` Found ${query1.Items.length} matches\n`);
// Query 2: Filter by first two sort key attributes (round + bracket)
console.log("Query 2: SEMIFINALS UPPER bracket matches");
const query2 = await docClient.send(new QueryCommand({
TableName: 'TournamentMatches',
IndexName: 'TournamentRegionIndex',
KeyConditionExpression: 'tournamentId = :tournament AND #region = :region AND round = :round AND bracket = :bracket',
ExpressionAttributeNames: {
'#region': 'region' // 'region' is a reserved keyword
},
ExpressionAttributeValues: {
':tournament': 'WINTER2024',
':region': 'NA-EAST',
':round': 'SEMIFINALS',
':bracket': 'UPPER'
}
}));
console.log(` Found ${query2.Items.length} matches\n`);
// Query 3: Filter by all three sort key attributes (round + bracket + matchId)
console.log("Query 3: Specific match in SEMIFINALS UPPER bracket");
const query3 = await docClient.send(new QueryCommand({
TableName: 'TournamentMatches',
IndexName: 'TournamentRegionIndex',
KeyConditionExpression: 'tournamentId = :tournament AND #region = :region AND round = :round AND bracket = :bracket AND matchId = :matchId',
ExpressionAttributeNames: {
'#region': 'region' // 'region' is a reserved keyword
},
ExpressionAttributeValues: {
':tournament': 'WINTER2024',
':region': 'NA-EAST',
':round': 'SEMIFINALS',
':bracket': 'UPPER',
':matchId': 'match-002'
}
}));
console.log(` Found ${query3.Items.length} matches\n`);
// Query 4: INVALID - skipping round
console.log("Query 4: Attempting to skip first sort key attribute (WILL FAIL)");
try {
const query4 = await docClient.send(new QueryCommand({
TableName: 'TournamentMatches',
IndexName: 'TournamentRegionIndex',
KeyConditionExpression: 'tournamentId = :tournament AND #region = :region AND bracket = :bracket',
ExpressionAttributeNames: {
'#region': 'region' // 'region' is a reserved keyword
},
ExpressionAttributeValues: {
':tournament': 'WINTER2024',
':region': 'NA-EAST',
':bracket': 'UPPER'
}
}));
} catch (error) {
console.log(` Error: ${error.message}`);
console.log(` Cannot skip sort key attributes - must query left-to-right\n`);
}
```
**Résultat attendu :**
```
Query 1: All SEMIFINALS matches
Found 2 matches
Query 2: SEMIFINALS UPPER bracket matches
Found 2 matches
Query 3: Specific match in SEMIFINALS UPPER bracket
Found 1 matches
Query 4: Attempting to skip first sort key attribute (WILL FAIL)
Error: Query key condition not supported
Cannot skip sort key attributes - must query left-to-right
```
**Left-to-right règles de requête :** vous devez interroger les attributs dans l'ordre de gauche à droite, sans en sauter aucun.
**Modèles valides :**
+ Premier attribut uniquement : `round = 'SEMIFINALS'`
+ Les deux premiers attributs : `round = 'SEMIFINALS' AND bracket = 'UPPER'`
+ Les trois attributs : `round = 'SEMIFINALS' AND bracket = 'UPPER' AND matchId = 'match-002'`
**Modèles non valides :**
+ Ignorer le premier attribut : `bracket = 'UPPER'` (saute le tour)
+ Interrogation hors ordre : `matchId = 'match-002' AND round = 'SEMIFINALS'`
+ Laisser des espaces : `round = 'SEMIFINALS' AND matchId = 'match-002'` (ne tient pas compte du crochet)
**Note**
**Conseil de conception :** Triez les attributs clés du plus général au plus spécifique afin d'optimiser la flexibilité des requêtes.
### Étape 5 : Utiliser les conditions d'inégalité sur les clés de tri de l'indice secondaire global
Les conditions d'inégalité doivent être la dernière condition de votre requête. Cet exemple montre comment utiliser les opérateurs de comparaison (`>=`,`BETWEEN`) et la correspondance de préfixes (`begins_with()`) sur les attributs clés de tri. Une fois que vous avez utilisé un opérateur d'inégalité, vous ne pouvez pas ajouter de conditions clés de tri supplémentaires après celui-ci. L'inégalité doit être la condition finale de votre expression de condition clé.
#### Exemple de code
```
import { DynamoDBClient } from "@aws-sdk/client-dynamodb";
import { DynamoDBDocumentClient, QueryCommand } from "@aws-sdk/lib-dynamodb";
const client = new DynamoDBClient({ region: 'us-west-2' });
const docClient = DynamoDBDocumentClient.from(client);
// Query 1: Round comparison (inequality on first sort key attribute)
console.log("Query 1: Matches from QUARTERFINALS onwards");
const query1 = await docClient.send(new QueryCommand({
TableName: 'TournamentMatches',
IndexName: 'TournamentRegionIndex',
KeyConditionExpression: 'tournamentId = :tournament AND #region = :region AND round >= :round',
ExpressionAttributeNames: {
'#region': 'region' // 'region' is a reserved keyword
},
ExpressionAttributeValues: {
':tournament': 'WINTER2024',
':region': 'NA-EAST',
':round': 'QUARTERFINALS'
}
}));
console.log(` Found ${query1.Items.length} matches\n`);
// Query 2: Round range with BETWEEN
console.log("Query 2: Matches between QUARTERFINALS and SEMIFINALS");
const query2 = await docClient.send(new QueryCommand({
TableName: 'TournamentMatches',
IndexName: 'TournamentRegionIndex',
KeyConditionExpression: 'tournamentId = :tournament AND #region = :region AND round BETWEEN :start AND :end',
ExpressionAttributeNames: {
'#region': 'region' // 'region' is a reserved keyword
},
ExpressionAttributeValues: {
':tournament': 'WINTER2024',
':region': 'NA-EAST',
':start': 'QUARTERFINALS',
':end': 'SEMIFINALS'
}
}));
console.log(` Found ${query2.Items.length} matches\n`);
// Query 3: Prefix matching with begins_with (treated as inequality)
console.log("Query 3: Matches in brackets starting with 'U'");
const query3 = await docClient.send(new QueryCommand({
TableName: 'TournamentMatches',
IndexName: 'TournamentRegionIndex',
KeyConditionExpression: 'tournamentId = :tournament AND #region = :region AND round = :round AND begins_with(bracket, :prefix)',
ExpressionAttributeNames: {
'#region': 'region' // 'region' is a reserved keyword
},
ExpressionAttributeValues: {
':tournament': 'WINTER2024',
':region': 'NA-EAST',
':round': 'SEMIFINALS',
':prefix': 'U'
}
}));
console.log(` Found ${query3.Items.length} matches\n`);
// Query 4: INVALID - condition after inequality
console.log("Query 4: Attempting condition after inequality (WILL FAIL)");
try {
const query4 = await docClient.send(new QueryCommand({
TableName: 'TournamentMatches',
IndexName: 'TournamentRegionIndex',
KeyConditionExpression: 'tournamentId = :tournament AND #region = :region AND round > :round AND bracket = :bracket',
ExpressionAttributeNames: {
'#region': 'region' // 'region' is a reserved keyword
},
ExpressionAttributeValues: {
':tournament': 'WINTER2024',
':region': 'NA-EAST',
':round': 'QUARTERFINALS',
':bracket': 'UPPER'
}
}));
} catch (error) {
console.log(` Error: ${error.message}`);
console.log(` Cannot add conditions after inequality - it must be last\n`);
}
```
**Règles relatives aux opérateurs d'inégalité :** vous pouvez utiliser des opérateurs de comparaison (`>``>=`,`<`,,`<=`) `BETWEEN` pour les requêtes de plage et `begins_with()` pour la correspondance de préfixes. L'inégalité doit être la dernière condition de votre requête.
**Modèles valides :**
+ Conditions d'égalité suivies d'inégalités : `round = 'SEMIFINALS' AND bracket = 'UPPER' AND matchId > 'match-001'`
+ Inégalité sur le premier attribut : `round BETWEEN 'QUARTERFINALS' AND 'SEMIFINALS'`
+ Correspondance du préfixe comme condition finale : `round = 'SEMIFINALS' AND begins_with(bracket, 'U')`
**Modèles non valides :**
+ Ajouter des conditions après une inégalité : `round > 'QUARTERFINALS' AND bracket = 'UPPER'`
+ En utilisant de multiples inégalités : `round > 'QUARTERFINALS' AND bracket > 'L'`
**Important**
`begins_with()`est traitée comme une condition d'inégalité, de sorte qu'aucune condition clé de tri supplémentaire ne peut la suivre.
### Étape 6 : Interroger l'index secondaire PlayerMatchHistoryIndex global avec une clé de tri à attributs multiples
Cet exemple interroge celui PlayerMatchHistoryIndex qui possède une clé de partition unique (`player1Id`) et une clé de tri multi-attributs (`matchDate`\$1`round`). Cela permet d'effectuer une analyse entre tournois en interrogeant tous les matchs pour un joueur spécifique sans connaître le tournoi, IDs alors que le tableau de base nécessiterait des requêtes distinctes par combinaison tournien-région.
#### Exemple de code
```
import { DynamoDBClient } from "@aws-sdk/client-dynamodb";
import { DynamoDBDocumentClient, QueryCommand } from "@aws-sdk/lib-dynamodb";
const client = new DynamoDBClient({ region: 'us-west-2' });
const docClient = DynamoDBDocumentClient.from(client);
// Query 1: All matches for Player 101 across all tournaments
console.log("Query 1: All matches for Player 101");
const query1 = await docClient.send(new QueryCommand({
TableName: 'TournamentMatches',
IndexName: 'PlayerMatchHistoryIndex',
KeyConditionExpression: 'player1Id = :player',
ExpressionAttributeValues: {
':player': '101'
}
}));
console.log(` Found ${query1.Items.length} matches for Player 101:`);
query1.Items.forEach(match => {
console.log(` ${match.tournamentId}/${match.region} - ${match.matchDate} - ${match.round}`);
});
console.log();
// Query 2: Player 101 matches on specific date
console.log("Query 2: Player 101 matches on 2024-01-18");
const query2 = await docClient.send(new QueryCommand({
TableName: 'TournamentMatches',
IndexName: 'PlayerMatchHistoryIndex',
KeyConditionExpression: 'player1Id = :player AND matchDate = :date',
ExpressionAttributeValues: {
':player': '101',
':date': '2024-01-18'
}
}));
console.log(` Found ${query2.Items.length} matches\n`);
// Query 3: Player 101 SEMIFINALS matches on specific date
console.log("Query 3: Player 101 SEMIFINALS matches on 2024-01-18");
const query3 = await docClient.send(new QueryCommand({
TableName: 'TournamentMatches',
IndexName: 'PlayerMatchHistoryIndex',
KeyConditionExpression: 'player1Id = :player AND matchDate = :date AND round = :round',
ExpressionAttributeValues: {
':player': '101',
':date': '2024-01-18',
':round': 'SEMIFINALS'
}
}));
console.log(` Found ${query3.Items.length} matches\n`);
// Query 4: Player 101 matches in date range
console.log("Query 4: Player 101 matches in January 2024");
const query4 = await docClient.send(new QueryCommand({
TableName: 'TournamentMatches',
IndexName: 'PlayerMatchHistoryIndex',
KeyConditionExpression: 'player1Id = :player AND matchDate BETWEEN :start AND :end',
ExpressionAttributeValues: {
':player': '101',
':start': '2024-01-01',
':end': '2024-01-31'
}
}));
console.log(` Found ${query4.Items.length} matches\n`);
```
## Variations de motifs
### Données chronologiques avec clés à attributs multiples
Optimisation pour les requêtes de séries chronologiques avec des attributs temporels hiérarchiques
#### Exemple de code
```
{
TableName: 'IoTReadings',
// Base table: Simple partition key
KeySchema: [
{ AttributeName: 'readingId', KeyType: 'HASH' }
],
AttributeDefinitions: [
{ AttributeName: 'readingId', AttributeType: 'S' },
{ AttributeName: 'deviceId', AttributeType: 'S' },
{ AttributeName: 'locationId', AttributeType: 'S' },
{ AttributeName: 'year', AttributeType: 'S' },
{ AttributeName: 'month', AttributeType: 'S' },
{ AttributeName: 'day', AttributeType: 'S' },
{ AttributeName: 'timestamp', AttributeType: 'S' }
],
// GSI with multi-attribute keys for time-series queries
GlobalSecondaryIndexes: [{
IndexName: 'DeviceLocationTimeIndex',
KeySchema: [
{ AttributeName: 'deviceId', KeyType: 'HASH' },
{ AttributeName: 'locationId', KeyType: 'HASH' },
{ AttributeName: 'year', KeyType: 'RANGE' },
{ AttributeName: 'month', KeyType: 'RANGE' },
{ AttributeName: 'day', KeyType: 'RANGE' },
{ AttributeName: 'timestamp', KeyType: 'RANGE' }
],
Projection: { ProjectionType: 'ALL' }
}],
BillingMode: 'PAY_PER_REQUEST'
}
// Query patterns enabled via GSI:
// - All readings for device in location
// - Readings for specific year
// - Readings for specific month in year
// - Readings for specific day
// - Readings in time range
```
**Avantages :** La hiérarchie temporelle naturelle (année → mois → jour → horodatage) permet des requêtes efficaces à tout moment avec une granularité sans analyse ou manipulation de dates. L'index secondaire global indexe automatiquement toutes les lectures en utilisant leurs attributs temporels naturels.
### Commandes de commerce électronique avec clés à attributs multiples
Suivez les commandes avec plusieurs dimensions
#### Exemple de code
```
{
TableName: 'Orders',
// Base table: Simple partition key
KeySchema: [
{ AttributeName: 'orderId', KeyType: 'HASH' }
],
AttributeDefinitions: [
{ AttributeName: 'orderId', AttributeType: 'S' },
{ AttributeName: 'sellerId', AttributeType: 'S' },
{ AttributeName: 'region', AttributeType: 'S' },
{ AttributeName: 'orderDate', AttributeType: 'S' },
{ AttributeName: 'category', AttributeType: 'S' },
{ AttributeName: 'customerId', AttributeType: 'S' },
{ AttributeName: 'orderStatus', AttributeType: 'S' }
],
GlobalSecondaryIndexes: [
{
IndexName: 'SellerRegionIndex',
KeySchema: [
{ AttributeName: 'sellerId', KeyType: 'HASH' },
{ AttributeName: 'region', KeyType: 'HASH' },
{ AttributeName: 'orderDate', KeyType: 'RANGE' },
{ AttributeName: 'category', KeyType: 'RANGE' },
{ AttributeName: 'orderId', KeyType: 'RANGE' }
],
Projection: { ProjectionType: 'ALL' }
},
{
IndexName: 'CustomerOrdersIndex',
KeySchema: [
{ AttributeName: 'customerId', KeyType: 'HASH' },
{ AttributeName: 'orderDate', KeyType: 'RANGE' },
{ AttributeName: 'orderStatus', KeyType: 'RANGE' }
],
Projection: { ProjectionType: 'ALL' }
}
],
BillingMode: 'PAY_PER_REQUEST'
}
// SellerRegionIndex GSI queries:
// - Orders by seller and region
// - Orders by seller, region, and date
// - Orders by seller, region, date, and category
// CustomerOrdersIndex GSI queries:
// - Customer's orders
// - Customer's orders by date
// - Customer's orders by date and status
```
### Données d'organisation hiérarchiques
Hiérarchies organisationnelles modélisées
#### Exemple de code
```
{
TableName: 'Employees',
// Base table: Simple partition key
KeySchema: [
{ AttributeName: 'employeeId', KeyType: 'HASH' }
],
AttributeDefinitions: [
{ AttributeName: 'employeeId', AttributeType: 'S' },
{ AttributeName: 'companyId', AttributeType: 'S' },
{ AttributeName: 'divisionId', AttributeType: 'S' },
{ AttributeName: 'departmentId', AttributeType: 'S' },
{ AttributeName: 'teamId', AttributeType: 'S' },
{ AttributeName: 'skillCategory', AttributeType: 'S' },
{ AttributeName: 'skillLevel', AttributeType: 'S' },
{ AttributeName: 'yearsExperience', AttributeType: 'N' }
],
GlobalSecondaryIndexes: [
{
IndexName: 'OrganizationIndex',
KeySchema: [
{ AttributeName: 'companyId', KeyType: 'HASH' },
{ AttributeName: 'divisionId', KeyType: 'HASH' },
{ AttributeName: 'departmentId', KeyType: 'RANGE' },
{ AttributeName: 'teamId', KeyType: 'RANGE' },
{ AttributeName: 'employeeId', KeyType: 'RANGE' }
],
Projection: { ProjectionType: 'ALL' }
},
{
IndexName: 'SkillsIndex',
KeySchema: [
{ AttributeName: 'skillCategory', KeyType: 'HASH' },
{ AttributeName: 'skillLevel', KeyType: 'RANGE' },
{ AttributeName: 'yearsExperience', KeyType: 'RANGE' }
],
Projection: { ProjectionType: 'INCLUDE', NonKeyAttributes: ['employeeId', 'name'] }
}
],
BillingMode: 'PAY_PER_REQUEST'
}
// OrganizationIndex GSI query patterns:
// - All employees in company/division
// - Employees in specific department
// - Employees in specific team
// SkillsIndex GSI query patterns:
// - Employees by skill and experience level
```
### Clés à attributs multiples éparses
Combinez des clés à attributs multiples pour créer un GSI clairsemé
#### Exemple de code
```
{
TableName: 'Products',
// Base table: Simple partition key
KeySchema: [
{ AttributeName: 'productId', KeyType: 'HASH' }
],
AttributeDefinitions: [
{ AttributeName: 'productId', AttributeType: 'S' },
{ AttributeName: 'categoryId', AttributeType: 'S' },
{ AttributeName: 'subcategoryId', AttributeType: 'S' },
{ AttributeName: 'averageRating', AttributeType: 'N' },
{ AttributeName: 'reviewCount', AttributeType: 'N' }
],
GlobalSecondaryIndexes: [
{
IndexName: 'CategoryIndex',
KeySchema: [
{ AttributeName: 'categoryId', KeyType: 'HASH' },
{ AttributeName: 'subcategoryId', KeyType: 'HASH' },
{ AttributeName: 'productId', KeyType: 'RANGE' }
],
Projection: { ProjectionType: 'ALL' }
},
{
IndexName: 'ReviewedProductsIndex',
KeySchema: [
{ AttributeName: 'categoryId', KeyType: 'HASH' },
{ AttributeName: 'averageRating', KeyType: 'RANGE' }, // Optional attribute
{ AttributeName: 'reviewCount', KeyType: 'RANGE' } // Optional attribute
],
Projection: { ProjectionType: 'ALL' }
}
],
BillingMode: 'PAY_PER_REQUEST'
}
// Only products with reviews appear in ReviewedProductsIndex GSI
// Automatic filtering without application logic
// Multi-attribute sort key enables rating and count queries
```
### SaaS multi-tenant
Plateforme SaaS multi-locataires avec isolation du client
#### Exemple de code
```
// Table design
{
TableName: 'SaasData',
// Base table: Simple partition key
KeySchema: [
{ AttributeName: 'resourceId', KeyType: 'HASH' }
],
AttributeDefinitions: [
{ AttributeName: 'resourceId', AttributeType: 'S' },
{ AttributeName: 'tenantId', AttributeType: 'S' },
{ AttributeName: 'customerId', AttributeType: 'S' },
{ AttributeName: 'resourceType', AttributeType: 'S' }
],
// GSI with multi-attribute keys for tenant-customer isolation
GlobalSecondaryIndexes: [{
IndexName: 'TenantCustomerIndex',
KeySchema: [
{ AttributeName: 'tenantId', KeyType: 'HASH' },
{ AttributeName: 'customerId', KeyType: 'HASH' },
{ AttributeName: 'resourceType', KeyType: 'RANGE' },
{ AttributeName: 'resourceId', KeyType: 'RANGE' }
],
Projection: { ProjectionType: 'ALL' }
}],
BillingMode: 'PAY_PER_REQUEST'
}
// Query GSI: All resources for tenant T001, customer C001
const resources = await docClient.send(new QueryCommand({
TableName: 'SaasData',
IndexName: 'TenantCustomerIndex',
KeyConditionExpression: 'tenantId = :tenant AND customerId = :customer',
ExpressionAttributeValues: {
':tenant': 'T001',
':customer': 'C001'
}
}));
// Query GSI: Specific resource type for tenant/customer
const documents = await docClient.send(new QueryCommand({
TableName: 'SaasData',
IndexName: 'TenantCustomerIndex',
KeyConditionExpression: 'tenantId = :tenant AND customerId = :customer AND resourceType = :type',
ExpressionAttributeValues: {
':tenant': 'T001',
':customer': 'C001',
':type': 'document'
}
}));
```
**Avantages :** requêtes efficaces dans le contexte locataire-client et organisation naturelle des données.
### Transactions financières
Le système bancaire suit les transactions du compte en utilisant GSIs
#### Exemple de code
```
// Table design
{
TableName: 'BankTransactions',
// Base table: Simple partition key
KeySchema: [
{ AttributeName: 'transactionId', KeyType: 'HASH' }
],
AttributeDefinitions: [
{ AttributeName: 'transactionId', AttributeType: 'S' },
{ AttributeName: 'accountId', AttributeType: 'S' },
{ AttributeName: 'year', AttributeType: 'S' },
{ AttributeName: 'month', AttributeType: 'S' },
{ AttributeName: 'day', AttributeType: 'S' },
{ AttributeName: 'transactionType', AttributeType: 'S' }
],
GlobalSecondaryIndexes: [
{
IndexName: 'AccountTimeIndex',
KeySchema: [
{ AttributeName: 'accountId', KeyType: 'HASH' },
{ AttributeName: 'year', KeyType: 'RANGE' },
{ AttributeName: 'month', KeyType: 'RANGE' },
{ AttributeName: 'day', KeyType: 'RANGE' },
{ AttributeName: 'transactionId', KeyType: 'RANGE' }
],
Projection: { ProjectionType: 'ALL' }
},
{
IndexName: 'TransactionTypeIndex',
KeySchema: [
{ AttributeName: 'accountId', KeyType: 'HASH' },
{ AttributeName: 'transactionType', KeyType: 'RANGE' },
{ AttributeName: 'year', KeyType: 'RANGE' },
{ AttributeName: 'month', KeyType: 'RANGE' }
],
Projection: { ProjectionType: 'ALL' }
}
],
BillingMode: 'PAY_PER_REQUEST'
}
// Query AccountTimeIndex GSI: All transactions for account in 2023
const yearTransactions = await docClient.send(new QueryCommand({
TableName: 'BankTransactions',
IndexName: 'AccountTimeIndex',
KeyConditionExpression: 'accountId = :account AND #year = :year',
ExpressionAttributeNames: { '#year': 'year' },
ExpressionAttributeValues: {
':account': 'ACC-12345',
':year': '2023'
}
}));
// Query AccountTimeIndex GSI: Transactions in specific month
const monthTransactions = await docClient.send(new QueryCommand({
TableName: 'BankTransactions',
IndexName: 'AccountTimeIndex',
KeyConditionExpression: 'accountId = :account AND #year = :year AND #month = :month',
ExpressionAttributeNames: { '#year': 'year', '#month': 'month' },
ExpressionAttributeValues: {
':account': 'ACC-12345',
':year': '2023',
':month': '11'
}
}));
// Query TransactionTypeIndex GSI: Deposits in 2023
const deposits = await docClient.send(new QueryCommand({
TableName: 'BankTransactions',
IndexName: 'TransactionTypeIndex',
KeyConditionExpression: 'accountId = :account AND transactionType = :type AND #year = :year',
ExpressionAttributeNames: { '#year': 'year' },
ExpressionAttributeValues: {
':account': 'ACC-12345',
':type': 'deposit',
':year': '2023'
}
}));
```
## Exemple complet
L'exemple suivant illustre les clés à attributs multiples, de la configuration au nettoyage :
### Exemple de code
```
import {
DynamoDBClient,
CreateTableCommand,
DeleteTableCommand,
waitUntilTableExists
} from "@aws-sdk/client-dynamodb";
import {
DynamoDBDocumentClient,
PutCommand,
QueryCommand
} from "@aws-sdk/lib-dynamodb";
const client = new DynamoDBClient({ region: 'us-west-2' });
const docClient = DynamoDBDocumentClient.from(client);
async function multiAttributeKeysDemo() {
console.log("Starting Multi-Attribute GSI Keys Demo\n");
// Step 1: Create table with GSIs using multi-attribute keys
console.log("1. Creating table with multi-attribute GSI keys...");
await client.send(new CreateTableCommand({
TableName: 'TournamentMatches',
KeySchema: [
{ AttributeName: 'matchId', KeyType: 'HASH' }
],
AttributeDefinitions: [
{ AttributeName: 'matchId', AttributeType: 'S' },
{ AttributeName: 'tournamentId', AttributeType: 'S' },
{ AttributeName: 'region', AttributeType: 'S' },
{ AttributeName: 'round', AttributeType: 'S' },
{ AttributeName: 'bracket', AttributeType: 'S' },
{ AttributeName: 'player1Id', AttributeType: 'S' },
{ AttributeName: 'matchDate', AttributeType: 'S' }
],
GlobalSecondaryIndexes: [
{
IndexName: 'TournamentRegionIndex',
KeySchema: [
{ AttributeName: 'tournamentId', KeyType: 'HASH' },
{ AttributeName: 'region', KeyType: 'HASH' },
{ AttributeName: 'round', KeyType: 'RANGE' },
{ AttributeName: 'bracket', KeyType: 'RANGE' },
{ AttributeName: 'matchId', KeyType: 'RANGE' }
],
Projection: { ProjectionType: 'ALL' }
},
{
IndexName: 'PlayerMatchHistoryIndex',
KeySchema: [
{ AttributeName: 'player1Id', KeyType: 'HASH' },
{ AttributeName: 'matchDate', KeyType: 'RANGE' },
{ AttributeName: 'round', KeyType: 'RANGE' }
],
Projection: { ProjectionType: 'ALL' }
}
],
BillingMode: 'PAY_PER_REQUEST'
}));
await waitUntilTableExists({ client, maxWaitTime: 120 }, { TableName: 'TournamentMatches' });
console.log("Table created\n");
// Step 2: Insert tournament matches
console.log("2. Inserting tournament matches...");
const matches = [
{ matchId: 'match-001', tournamentId: 'WINTER2024', region: 'NA-EAST', round: 'FINALS', bracket: 'CHAMPIONSHIP', player1Id: '101', player2Id: '103', matchDate: '2024-01-20', winner: '101', score: '3-1' },
{ matchId: 'match-002', tournamentId: 'WINTER2024', region: 'NA-EAST', round: 'SEMIFINALS', bracket: 'UPPER', player1Id: '101', player2Id: '105', matchDate: '2024-01-18', winner: '101', score: '3-2' },
{ matchId: 'match-003', tournamentId: 'WINTER2024', region: 'NA-WEST', round: 'FINALS', bracket: 'CHAMPIONSHIP', player1Id: '102', player2Id: '104', matchDate: '2024-01-20', winner: '102', score: '3-2' },
{ matchId: 'match-004', tournamentId: 'SPRING2024', region: 'NA-EAST', round: 'QUARTERFINALS', bracket: 'UPPER', player1Id: '101', player2Id: '108', matchDate: '2024-03-15', winner: '101', score: '3-0' }
];
for (const match of matches) {
await docClient.send(new PutCommand({ TableName: 'TournamentMatches', Item: match }));
}
console.log(`Inserted ${matches.length} tournament matches\n`);
// Step 3: Query GSI with multi-attribute partition key
console.log("3. Query TournamentRegionIndex GSI: WINTER2024/NA-EAST matches");
const gsiQuery1 = await docClient.send(new QueryCommand({
TableName: 'TournamentMatches',
IndexName: 'TournamentRegionIndex',
KeyConditionExpression: 'tournamentId = :tournament AND #region = :region',
ExpressionAttributeNames: { '#region': 'region' },
ExpressionAttributeValues: { ':tournament': 'WINTER2024', ':region': 'NA-EAST' }
}));
console.log(` Found ${gsiQuery1.Items.length} matches:`);
gsiQuery1.Items.forEach(match => {
console.log(` ${match.round} - ${match.bracket} - ${match.winner} won`);
});
// Step 4: Query GSI with multi-attribute sort key
console.log("\n4. Query PlayerMatchHistoryIndex GSI: All matches for Player 101");
const gsiQuery2 = await docClient.send(new QueryCommand({
TableName: 'TournamentMatches',
IndexName: 'PlayerMatchHistoryIndex',
KeyConditionExpression: 'player1Id = :player',
ExpressionAttributeValues: { ':player': '101' }
}));
console.log(` Found ${gsiQuery2.Items.length} matches for Player 101:`);
gsiQuery2.Items.forEach(match => {
console.log(` ${match.tournamentId}/${match.region} - ${match.matchDate} - ${match.round}`);
});
console.log("\nDemo complete");
console.log("No synthetic keys needed - GSIs use native attributes automatically");
}
async function cleanup() {
console.log("Deleting table...");
await client.send(new DeleteTableCommand({ TableName: 'TournamentMatches' }));
console.log("Table deleted");
}
// Run demo
multiAttributeKeysDemo().catch(console.error);
// Uncomment to cleanup:
// cleanup().catch(console.error);
```
**Échafaudage de code minimal**
### Exemple de code
```
// 1. Create table with GSI using multi-attribute keys
await client.send(new CreateTableCommand({
TableName: 'MyTable',
KeySchema: [
{ AttributeName: 'id', KeyType: 'HASH' } // Simple base table PK
],
AttributeDefinitions: [
{ AttributeName: 'id', AttributeType: 'S' },
{ AttributeName: 'attr1', AttributeType: 'S' },
{ AttributeName: 'attr2', AttributeType: 'S' },
{ AttributeName: 'attr3', AttributeType: 'S' },
{ AttributeName: 'attr4', AttributeType: 'S' }
],
GlobalSecondaryIndexes: [{
IndexName: 'MyGSI',
KeySchema: [
{ AttributeName: 'attr1', KeyType: 'HASH' }, // GSI PK attribute 1
{ AttributeName: 'attr2', KeyType: 'HASH' }, // GSI PK attribute 2
{ AttributeName: 'attr3', KeyType: 'RANGE' }, // GSI SK attribute 1
{ AttributeName: 'attr4', KeyType: 'RANGE' } // GSI SK attribute 2
],
Projection: { ProjectionType: 'ALL' }
}],
BillingMode: 'PAY_PER_REQUEST'
}));
// 2. Insert items with native attributes (no concatenation needed for GSI)
await docClient.send(new PutCommand({
TableName: 'MyTable',
Item: {
id: 'item-001',
attr1: 'value1',
attr2: 'value2',
attr3: 'value3',
attr4: 'value4',
// ... other attributes
}
}));
// 3. Query GSI with all partition key attributes
await docClient.send(new QueryCommand({
TableName: 'MyTable',
IndexName: 'MyGSI',
KeyConditionExpression: 'attr1 = :v1 AND attr2 = :v2',
ExpressionAttributeValues: {
':v1': 'value1',
':v2': 'value2'
}
}));
// 4. Query GSI with sort key attributes (left-to-right)
await docClient.send(new QueryCommand({
TableName: 'MyTable',
IndexName: 'MyGSI',
KeyConditionExpression: 'attr1 = :v1 AND attr2 = :v2 AND attr3 = :v3',
ExpressionAttributeValues: {
':v1': 'value1',
':v2': 'value2',
':v3': 'value3'
}
}));
// Note: If any attribute name is a DynamoDB reserved keyword, use ExpressionAttributeNames:
// KeyConditionExpression: 'attr1 = :v1 AND #attr2 = :v2'
// ExpressionAttributeNames: { '#attr2': 'attr2' }
```
## Ressources supplémentaires
+ [Meilleures pratiques DynamoDB](https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/best-practices.html)
+ [Utilisation de tables et de données](https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/WorkingWithTables.html)
+ [Index secondaires globaux](https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/GSI.html)
+ [Opérations de requête et de numérisation](https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/Query.html)
# Gestion des index secondaires globaux dans DynamoDB
Cette section décrit comment créer, modifier et supprimer des index secondaires globaux dans Amazon DynamoDB.
**Topics**
+ [Création d’une table avec des index secondaires globaux](#GSI.Creating)
+ [Description des index secondaires globaux sur une table](#GSI.Describing)
+ [Ajout d’un index secondaire global à une table existante](#GSI.OnlineOps.Creating)
+ [Suppression d’un index secondaire global](#GSI.OnlineOps.Deleting)
+ [Modification d’un index secondaire global pendant la création](#GSI.OnlineOps.Creating.Modify)
## Création d’une table avec des index secondaires globaux
Pour créer une table avec un ou plusieurs index secondaires globaux, utilisez l’opération `CreateTable` avec le paramètre `GlobalSecondaryIndexes`. Pour bénéficier d’une flexibilité de requête maximum, vous pouvez créer jusqu’à 20 index secondaires globaux (quota par défaut) par table.
Vous devez spécifier un attribut faisant office de clé de partition d’index. Vous pouvez éventuellement spécifier un autre attribut pour la clé de tri d’index. Il n’est pas nécessaire que l’un de ces attributs de clé soit identique à un attribut de clé dans la table. Par exemple, dans le *GameScores*tableau (voir[Utilisation d’index secondaires globaux dans DynamoDB](GSI.md)), il n'`TopScoreDateTime`y a `TopScore` pas non plus d'attributs clés. Vous pouvez créer un index secondaire global avec une clé de partition `TopScore` et une clé de tri `TopScoreDateTime`. Vous pouvez utiliser un tel index pour déterminer s’il existe une corrélation entre les scores d’une partie et l’heure de la journée à laquelle celle-ci est jouée.
Chaque attribut de clé d’index doit être un scalaire de type `String`, `Number` ou `Binary` (il ne peut pas être de type document ou ensemble). Vous pouvez projeter des attributs de tout type de données dans un index secondaire global. Celui-ci inclut des scalaires, des documents et des ensembles. Pour obtenir la liste complète des types de données, consultez [Types de données](HowItWorks.NamingRulesDataTypes.md#HowItWorks.DataTypes).
Si vous utilisez le mode approvisionné, vous devez fournir les paramètres `ProvisionedThroughput` pour l’index, à savoir `ReadCapacityUnits` et `WriteCapacityUnits`. Ces paramètres de débit approvisionné sont distincts de ceux de la table, mais se comportent de la même manière. Pour de plus amples informations, veuillez consulter [Considérations sur le débit alloué pour les index secondaires globaux](GSI.md#GSI.ThroughputConsiderations).
Les index secondaires globaux héritent du mode read/write capacité de la table de base. Pour de plus amples informations, veuillez consulter [Considérations relatives au changement de mode de capacité dans DynamoDB](bp-switching-capacity-modes.md).
**Note**
Lors de la création d’un nouvel index secondaire global, il peut être important de vérifier si la clé de partition de votre choix produit une distribution inégale ou réduite des données ou du trafic entre les valeurs des clés de partition du nouvel index. Si cela se produit, vous pourriez voir des opérations de remplissage et d’écriture se produire en même temps et limiter les écritures dans la table de base. Le service prend des mesures pour minimiser l’éventualité de ce scénario, mais il n’a aucune idée de la forme des données client par rapport à la clé de partition d’index, à la projection choisie ou à la rareté de la clé primaire d’index.
Si vous pensez que votre nouvel index secondaire global peut présenter des données ou une distribution de trafic étroites ou asymétriques entre les valeurs des clés de partition, tenez compte des points suivants avant d’ajouter de nouveaux index à des tables importantes sur le plan opérationnel.
Il peut être plus sûr d’ajouter l’index au moment où votre application génère le moins de trafic.
Envisagez d'activer CloudWatch Contributor Insights sur votre table de base et vos index. Cela vous procurera des informations précieuses sur la distribution de votre trafic.
Surveillez `WriteThrottleEvents` et `ThrottledRequests` mesurez `OnlineIndexPercentageProgress` CloudWatch tout au long du processus. Ajustez la capacité d'écriture allouée selon les besoins pour terminer le remblayage dans un délai raisonnable sans aucun effet de limitation significatif sur vos opérations en cours. `OnlineIndexConsumedWriteCapacity`et `OnlineThrottleEvents` devraient afficher 0 lors du remblayage de l'indice.
Préparez-vous à annuler la création de l'index si vous subissez un impact opérationnel dû à la limitation des écritures.
## Description des index secondaires globaux sur une table
Pour afficher l’état de tous les index secondaires globaux sur une table, utilisez l’opération `DescribeTable`. La portion `GlobalSecondaryIndexes` de la réponse affiche tous les index sur la table, ainsi que l’état actuel de chacun d’eux (`IndexStatus`).
L’état `IndexStatus` d’un index secondaire global peut être l’un des suivants :
+ `CREATING` – L’index est en cours de création et n’est pas encore disponible pour utilisation.
+ `ACTIVE` – L’index est prêt pour utilisation et les applications peuvent effectuer des opérations `Query` dessus.
+ `UPDATING` – Les paramètres de débit approvisionné de l’index sont en cours de modification.
+ `DELETING` – L’index est actuellement en cours de suppression et ne peut plus être utilisé.
Quand DynamoDB a fini de générer un index secondaire global, l’état de celui-ci passe de `CREATING` à `ACTIVE`.
## Ajout d’un index secondaire global à une table existante
Pour ajouter un index secondaire global à une table existante, utilisez l’opération `UpdateTable` avec le paramètre `GlobalSecondaryIndexUpdates`. Vous devez fournir les informations suivantes :
+ Un nom d’index. Le nom doit être unique parmi tous les index sur cette table.
+ Le schéma de clé de l’index. Vous devez spécifier un attribut pour la clé de partition d’index. Vous pouvez éventuellement spécifier un autre attribut pour la clé de tri d’index. Il n’est pas nécessaire que l’un de ces attributs de clé soit identique à un attribut de clé dans la table. Les types de données pour chaque attribut de schéma doivent être scalaires : `String`, `Number` ou `Binary`.
+ Attributs à projeter à partir de la table dans l’index :
+ `KEYS_ONLY` – Chaque élément de l’index se compose uniquement des valeurs de clé de partition et de tri de la table, ainsi que des valeurs de clé d’index.
+ `INCLUDE` – En plus des attributs décrits dans `KEYS_ONLY`, l’index secondaire inclut des attributs autres que de clé que vous spécifiez.
+ `ALL` – L’index inclut tous les attributs de la table source.
+ Les paramètres de débit approvisionné pour l’index, à savoir `ReadCapacityUnits` et `WriteCapacityUnits`. Ces paramètres de débit approvisionné sont distincts de ceux de la table.
Vous ne pouvez créer qu'un seul index secondaire global par opération `UpdateTable`.
### Phases de création d'index
Lorsque vous ajoutez un nouvel index secondaire global à une table existante, la table reste disponible pendant la création de l’index. Toutefois, le nouvel index n’est pas disponible pour les opérations Query tant que son état n’est pas passé de `CREATING` à `ACTIVE`.
**Note**
La création d’un index secondaire global n’utilise pas la scalabilité automatique des applications. L’augmentation de la capacité de scalabilité automatique des applications `MIN` ne réduit pas le temps de création de l’index secondaire global.
En coulisses, DynamoDB génère l’index en deux phases :
**Allocation de ressources**
DynamoDB alloue les ressources de calcul et de stockage nécessaires à la génération de l’index.
Au cours de la phase d’allocation des ressources, l’attribut `IndexStatus` est `CREATING`, et l’attribut `Backfilling` a la valeur false. Utilisez l’opération `DescribeTable` pour récupérer l’état d’une table et de tous ses index secondaires.
Pendant que l’index est en phase d’allocation de ressources, vous ne pouvez pas supprimer l’index ou sa table parent. Vous ne pouvez pas non plus modifier le débit approvisionné de l’index ou de la table. Vous ne pouvez pas ajouter ou supprimer d’autres index sur la table. En revanche, vous pouvez modifier le débit approvisionné de ces autres index.
**Remplissage**
Pour chaque élément de la table, DynamoDB détermine l’ensemble d’attributs à écrire dans l’index en fonction de sa projection (`KEYS_ONLY`, `INCLUDE` ou `ALL`). Il écrit ensuite ces attributs dans l’index. Durant la phase de remplissage, DynamoDB suit les éléments ajoutés, supprimés ou mis à jour dans la table. Les attributs de ces éléments sont également ajoutés, supprimés ou mis à jour dans l’index, selon le cas.
Au cours de la phase de remplissage, l’attribut `IndexStatus` est défini sur `CREATING`, et l’attribut `Backfilling` a la valeur true. Utilisez l’opération `DescribeTable` pour récupérer l’état d’une table et de tous ses index secondaires.
Pendant le remplissage de l’index, vous ne pouvez pas supprimer sa table parent. Vous pouvez cependant toujours supprimer l’index ou modifier le débit approvisionné de la table et de n’importe lequel de ses index secondaires globaux.
Pendant la phase de remplissage, certaines écritures d’éléments violant le schéma de clé peuvent aboutir tandis que d’autres sont rejetées. Après le remplissage, toutes les écritures dans les éléments, qui violent le schéma de clé du nouvel index sont rejetées. Nous vous recommandons d’exécuter l’outil de détection des violations une fois la phase de remplissage terminée afin de détecter et résoudre d’éventuelles violations de clé. Pour de plus amples informations, veuillez consulter [Détection et correction des violations de clé d’index dans DynamoDB](GSI.OnlineOps.ViolationDetection.md).
Pendant les phases d’allocation de ressources et de remplissage, l’index est dans l’état `CREATING`. Pendant ce temps, DynamoDB effectue des opérations de lecture sur la table. Vous n’êtes pas facturé pour les opérations de lecture de la table de base destinées au remplissage de l’index secondaire global.
Une fois la génération de l’index terminée, l’état passe à `ACTIVE`. Vous ne pouvez pas effectuer d’opération `Query` ou `Scan` sur l’index tant que l’état de celui-ci n’est pas `ACTIVE`.
**Note**
Dans certains cas, DynamoDB ne peut pas écrire des données de la table dans l’index en raison de violations de clé d’index. Cela peut se produire si :
Le type de données d’une valeur d’attribut ne correspond pas au type de données d’un type de données de schéma de clé d’index.
La taille d’un attribut dépasse la longueur maximale définie pour un attribut de clé d’index.
Un attribut de clé d’index a une valeur de String ou de Binary attribute vide.
Les violations de clé d’index n’interfèrent pas avec la création d’index secondaire global. Cependant, quand l’index passe à l’état `ACTIVE`, il ne contient plus de clé violant le schéma de clé.
DynamoDB fournit un outil autonome pour détecter et résoudre ces problèmes. Pour de plus amples informations, veuillez consulter [Détection et correction des violations de clé d’index dans DynamoDB](GSI.OnlineOps.ViolationDetection.md).
### Ajout d’un index secondaire global à une table volumineuse
Le temps nécessaire à la génération d’un index secondaire global dépend de plusieurs facteurs, tels que les suivants :
+ La taille de la table
+ Le nombre d’éléments dans la table pouvant être inclus dans l’index
+ Le nombre d’attributs projetés dans l’index
+ L’activité d’écriture sur la table principale pendant les générations d’index
Si vous ajoutez un index secondaire global à une table très volumineuse, le processus de création peut prendre beaucoup de temps. Pour suivre la progression et déterminer si la capacité d'écriture de l'index est suffisante, consultez les CloudWatch statistiques Amazon suivantes :
+ `OnlineIndexPercentageProgress`
Pour plus d'informations sur CloudWatch les métriques associées à DynamoDB, consultez. [Métriques DynamoDB](metrics-dimensions.md#dynamodb-metrics)
**Important**
Vous devrez peut-être autoriser la mise en liste d’autorisation de très grandes tables avant de créer ou de mettre à jour un index secondaire global. Contactez le AWS Support pour autoriser la mise en liste de vos tables.
Pendant le remplissage d’un index, DynamoDB utilise la capacité système interne pour lire la table. Cela permet de minimiser l’impact de la création d’index et de s’assurer que la table ne manque pas de capacité de lecture.
## Suppression d’un index secondaire global
Si vous n’avez plus besoin d’un index secondaire global, vous pouvez le supprimer à l’aide de l’opération `UpdateTable`.
Vous ne pouvez supprimer qu’un seul index secondaire global par opération `UpdateTable`.
Le processus de suppression de l’index secondaire global n’a aucune incidence sur les activités de lecture ou d’écriture dans la table parent. Pendant la suppression, vous pouvez toujours modifier le débit approvisionné sur d’autres index.
**Note**
Lorsque vous supprimez une table à l’aide de l’action `DeleteTable`, tous les index secondaires globaux sur cette table sont également supprimés.
Votre compte ne sera pas facturé pour l’opération de suppression de l’index secondaire global.
## Modification d’un index secondaire global pendant la création
Pendant la génération d’un index, vous pouvez utiliser l’opération `DescribeTable` pour déterminer la phase en cours. La description de l’index inclut un attribut booléen, `Backfilling`, indiquant si DynamoDB est en train de charger l’index avec les éléments de la table. Si la valeur de `Backfilling` est true, la phase d’allocation de ressources est terminée et le remplissage de l’index est en cours.
Pendant la phase de remplissage, vous pouvez supprimer l’index en cours de création. Au cours de cette phase, vous ne pouvez pas ajouter ou supprimer d’autres index sur la table.
**Note**
Pour les index créés dans le cadre d’une opération `CreateTable`, l’attribut `Backfilling` n’apparaît pas dans la sortie `DescribeTable`. Pour de plus amples informations, veuillez consulter [Phases de création d'index](#GSI.OnlineOps.Creating.Phases).
# Détection et correction des violations de clé d’index dans DynamoDB
Durant la phase de remplissage du processus de création d’index secondaire global, Amazon DynamoDB examine chaque élément de la table pour déterminer s’il peut être inclus dans l’index. Il se peut que certains éléments ne soient pas être éligibles parce qu’ils provoqueraient des violations de clé d’index. Dans ce cas, ces éléments restent dans la table, mais l’index ne contient pas d’entrée correspondante.
Une *violation de clé d’index* se produit dans les situations suivantes :
+ Il existe une discordance de type de données entre une valeur d’attribut et le type de données du schéma de clé d’index. Par exemple, supposons que l’un des éléments de la table `GameScores` a une valeur `TopScore` de type `String`. Si vous ajoutiez un index secondaire global avec une clé de partition `TopScore` de type `Number`, l’élément de la table violerait la clé d’index.
+ Une valeur d’attribut de la table dépasse la longueur maximum pour un attribut de clé d’index. La longueur maximum d’une clé de partition est de 2 048 octets, et la longueur maximum d’une clé de tri est de 1 024 octets. Si l’une des valeurs d’attribut correspondantes dans la table dépasse ces limites, l’élément de la table viole la clé d’index.
**Note**
Si une valeur de String ou de Binary attribute est définie pour un attribut utilisé comme clé d’index, la valeur d’attribut doit avoir une longueur supérieure à zéro ; sinon, l’élément de la table viole la clé d’index.
Cet outil ne signale pas cette violation de clé d’index, pour le moment.
Si une violation de clé d’index se produit, la phase de remplissage se poursuit sans interruption. Toutefois, les éléments violant le schéma de clé ne sont pas inclus dans l’index. Une fois la phase de remplissage terminée, toutes les écritures dans des éléments, qui violent le schéma de clé du nouvel index sont rejetées.
Pour identifier et corriger les valeurs d’attribut dans une table, qui violent une clé d’index, utilisez l’outil de détection des violations. Pour exécuter l’outil de détection des violations, vous créez un fichier de configuration qui spécifie le nom d’une table à analyser, les noms et les types de données des clés de partition et de tri d’index secondaire global, ainsi que les actions à entreprendre en cas détection de violations de clé d’index. L’outil de détection des violations peut opérer dans l’un des deux modes suivants :
+ **Mode détection** – Détecter les violations de clé d’index. Utilisez le mode de détection pour signaler les éléments de la table qui provoqueraient des violations de clé dans un index secondaire global (vous pouvez éventuellement demander que ces éléments de table violant le schéma de clé soient supprimés immédiatement quand ils sont détectés). La sortie du mode détection est écrite dans un fichier que vous pouvez utiliser pour une analyse plus approfondie.
+ **Mode correction** – Corriger les violations de clé d’index. En mode correction, l’outil de détection des violations lit un fichier d’entrée du même format que le fichier de sortie du mode détection. Le mode correction lit les enregistrements du fichier d’entrée et, pour chacun d’eux, supprime ou met à jour les éléments correspondants dans la table (notez que, si vous choisissez de mettre à jour les éléments, vous devez modifier le fichier d’entrée et définir des valeurs appropriées pour ces mises à jour).
## Téléchargement et exécution de l’outil de détection des violations
L’outil de détection des violations est disponible en tant qu’archive Java exécutable (fichier `.jar`), et s’exécute sur les ordinateurs Windows, macOS ou Linux. L’outil de détection des violations requiert Java 1.7 (ou version ultérieure) et Apache Maven.
+ [Téléchargez le détecteur de violations depuis GitHub](https://github.com/awslabs/dynamodb-online-index-violation-detector)
Suivez les instructions figurant dans le fichier `README.md` pour télécharger et installer l’outil de détection des violations à l’aide de Maven.
Pour démarrer l’outil de détection des violations, accédez au répertoire dans lequel vous avez généré le fichier `ViolationDetector.java`, puis entrez la commande suivante.
```
java -jar ViolationDetector.jar [options]
```
La ligne de commande de l’outil de détection des violations accepte les options suivantes :
+ `-h | --help` – Affiche un résumé et des options d’utilisation pour l’outil de détection des violations.
+ `-p | --configFilePath` `value` – Nom complet d’un fichier de configuration de l’outil de détection des violations. Pour de plus amples informations, veuillez consulter [Fichier de configuration de l’outil de détection des violations](#GSI.OnlineOps.ViolationDetection.ConfigFile).
+ `-t | --detect` `value` – Détecte les violations de clé d’index dans la table, et les écris dans le fichier de sortie de l’outil de détection des violations. Si la valeur de ce paramètre est définie sur `keep`, les éléments comportant des violations de clé ne sont pas modifiés. Si la valeur est définie sur `delete`, les éléments comportant des violations de clé sont supprimés de la table.
+ `-c | --correct` `value` – Lit les violations de clé d’index à partir d’un fichier d’entrée, et prend des mesures correctives sur les éléments de la table. Si la valeur de ce paramètre est définie sur `update`, les éléments comportant des violations de clé sont mis à jour avec de nouvelles valeurs ne violant pas le schéma de clé. Si la valeur est définie sur `delete`, les éléments comportant des violations de clé sont supprimés de la table.
## Fichier de configuration de l’outil de détection des violations
Lors de l’exécution, l’outil de détection des violations nécessite un fichier de configuration. Les paramètres de ce fichier déterminent les ressources DynamoDB auxquelles l’outil de détection des violations peut accéder, ainsi que le débit approvisionné qu’il peut consommer. Le tableau suivant décrit ces paramètres.
****
| Nom du paramètre | Description | Obligatoire ? |
| --- | --- | --- |
| `awsCredentialsFile` | Le nom complet d’un fichier contenant vos informations d’identification AWS . Le format du fichier contenant les informations d’identification doit être le suivant : accessKey = access_key_id_goes_here
secretKey = secret_key_goes_here
| Oui |
| `dynamoDBRegion` | AWS Région dans laquelle se trouve la table. Par exemple : `us-west-2`. | Oui |
| `tableName` | Le nom de la table DynamoDB à analyser. | Oui |
| `gsiHashKeyName` | Le nom de la clé de partition d’index. | Oui |
| `gsiHashKeyType` | Le type de données de la clé de partition d’index, à savoir `String`, `Number` ou `Binary` : `S \| N \| B` | Oui |
| `gsiRangeKeyName` | Le nom de la clé de tri d’index. Ne spécifiez pas ce paramètre si l’index n’a qu’une clé primaire simple (clé de partition). | Non |
| `gsiRangeKeyType` | Le type de données de la clé de tri d’index, à savoir `String`, `Number` ou `Binary` : `S \| N \| B` Ne spécifiez pas ce paramètre si l’index n’a qu’une clé primaire simple (clé de partition). | Non |
| `recordDetails` | Indication relative à l’écriture des détails des violations de clé d’index dans le fichier de sortie. Si la valeur est définie sur `true` (par défaut), les informations complètes sur les éléments violant le schéma de clé sont rapportées. Si la valeur est définie sur `false`, seul le nombre de violations est rapporté. | Non |
| `recordGsiValueInViolationRecord` | Indication relative à l’écriture des valeurs des violations de clé d’index dans le fichier de sortie. Si la valeur est définie sur `true` (par défaut), les valeurs de clés sont rapportées. Si la valeur est définie sur `false`, les valeurs de clés sont rapportées. | Non |
| `detectionOutputPath` | Le chemin d’accès complet du fichier de sortie de l’outil de détection des violations. Ce paramètre prend en charge l’écriture dans un répertoire local ou sur Amazon Simple Storage Service (Amazon S3). Voici quelques exemples : `detectionOutputPath = ``//local/path/filename.csv` `detectionOutputPath = ``s3://bucket/filename.csv` Les informations figurant dans le fichier de sortie s’affichent au format CSV (valeurs séparées par des virgules). Si vous ne définissez pas `detectionOutputPath`, le fichier de sortie est nommé `violation_detection.csv` et écrit dans votre répertoire de travail actuel. | Non |
| `numOfSegments` | Le nombre de segments d’analyse parallèle à utiliser quand l’outil de détection des violations analyse la table. La valeur par défaut est 1, ce qui signifie que la table est analysée de manière séquentielle. Si la valeur est égale ou supérieure à 2, l’outil de détection des violations divise la table en plusieurs segments logiques et un nombre égal d’unités d’exécution d’analyse. La valeur maximum de `numOfSegments` est 4 096.Pour les tables plus volumineuses, une analyse parallèle est généralement plus rapide qu’une analyse séquentielle. En outre, si la table est suffisamment grande pour couvrir plusieurs partitions, une analyse parallèle répartit uniformément son activité de lecture sur plusieurs partitions.Pour plus d’informations sur les analyses parallèles dans DynamoDB, consultez [Analyse parallèle](Scan.md#Scan.ParallelScan). | Non |
| `numOfViolations` | La limite supérieure des violations de clé d’index à écrire dans le fichier de sortie. Si la valeur est définie sur `-1` (par défaut), la table entière est analysée. Si la valeur est définie sur un nombre entier positif, l’outil de détection des violations s’arrête après avoir rencontré ce nombre de violations. | Non |
| `numOfRecords` | Le nombre d’éléments de la table à analyser. Si la valeur est définie sur (par défaut), la table entière est analysée. Si la valeur est définie sur un nombre entier positif, l’outil de détection des violations s’arrête après avoir analysé ce nombre d’éléments de la table. | Non |
| `readWriteIOPSPercent` | Régule le pourcentage d’unités de capacité de lecture approvisionnée qui sont consommées pendant l’analyse de la table. La plage des valeurs valides s’étend de `1` à `100`. La valeur par défaut (`25`) signifie que l’outil de détection des violations ne consommera pas plus de 25 % du débit de lecture approvisionné de la table. | Non |
| `correctionInputPath` | Chemin d’accès complet du fichier d’entrée de correction de l’outil de détection des violations. Si vous exécutez l’outil de détection des violations en mode correction, le contenu de ce fichier est utilisé pour modifier ou supprimer les éléments de données dans la table, qui violent l’index secondaire global. Le format du fichier `correctionInputPath` est identique à celui du fichier `detectionOutputPath`. Cela vous permet de traiter la sortie du mode détection comme entrée en mode correction. | Non |
| `correctionOutputPath` | Chemin d’accès complet du fichier de sortie de correction de l’outil de détection des violations. Ce fichier n’est créé que s’il y a des erreurs de mise à jour. Ce paramètre prend en charge l’écriture dans un répertoire local ou sur Amazon S3. Voici quelques exemples : `correctionOutputPath = ``//local/path/filename.csv` `correctionOutputPath = ``s3://bucket/filename.csv` Les informations figurant dans le fichier de sortie s’affichent au format CSV. Si vous ne définissez pas `correctionOutputPath`, le fichier de sortie est nommé `violation_update_errors.csv` et écrit dans votre répertoire de travail actuel. | Non |
## Détection
Pour détecter les violations de clé d’index, utilisez l’outil de détection des violations avec l’option de ligne de commande `--detect`. Pour voir le fonctionnement de cette option, considérez le tableau `ProductCatalog`. Voici la liste des éléments de la table. Seule la clé primaire (`Id`) et l’attribut `Price` sont affichés.
****
| Id (clé primaire) | Price |
| --- | --- |
| 101 | 5 |
| 102 | 20 |
| 103 | 200 |
| 201 | 100 |
| 202 | 200 |
| 203 | 300 |
| 204 | 400 |
| 205 | 500 |
Toutes les valeurs pour `Price` sont de type `Number`. Cependant, DynamoDB étant sans schéma, il est possible d’ajouter un élément avec une valeur `Price` non numérique. Par exemple, supposons que vous ajoutez un autre élément à la table `ProductCatalog`.
****
| Id (clé primaire) | Price |
| --- | --- |
| 999 | "Hello" |
La table totalise maintenant neuf éléments.
Vous ajoutez à présent un nouvel index secondaire global à la table : `PriceIndex`. La clé primaire pour cet index est une clé de partition, `Price`, de type `Number`. Une fois l’index généré, il contient huit éléments, tandis que la table `ProductCatalog` en contient neuf. La raison de cette différence est que la valeur `"Hello"` est de type `String`, alors que `PriceIndex` a une clé primaire de type `Number`. La valeur `String` violant la clé d’index secondaire globale, elle n’est pas présente dans l’index.
Pour utiliser l’outil de détection des violations dans ce scénario, vous devez d’abord créer un fichier de configuration tel que le suivant.
```
# Properties file for violation detection tool configuration.
# Parameters that are not specified will use default values.
awsCredentialsFile = /home/alice/credentials.txt
dynamoDBRegion = us-west-2
tableName = ProductCatalog
gsiHashKeyName = Price
gsiHashKeyType = N
recordDetails = true
recordGsiValueInViolationRecord = true
detectionOutputPath = ./gsi_violation_check.csv
correctionInputPath = ./gsi_violation_check.csv
numOfSegments = 1
readWriteIOPSPercent = 40
```
Ensuite, vous exécutez l’outil de détection des violations comme dans l’exemple suivant.
```
$ java -jar ViolationDetector.jar --configFilePath config.txt --detect keep
Violation detection started: sequential scan, Table name: ProductCatalog, GSI name: PriceIndex
Progress: Items scanned in total: 9, Items scanned by this thread: 9, Violations found by this thread: 1, Violations deleted by this thread: 0
Violation detection finished: Records scanned: 9, Violations found: 1, Violations deleted: 0, see results at: ./gsi_violation_check.csv
```
Si le paramètre de configuration `recordDetails` est défini sur `true`, l’outil de détection des violations écrit les détails de chaque violation dans le fichier de sortie, comme dans l’exemple suivant.
```
Table Hash Key,GSI Hash Key Value,GSI Hash Key Violation Type,GSI Hash Key Violation Description,GSI Hash Key Update Value(FOR USER),Delete Blank Attributes When Updating?(Y/N)
999,"{""S"":""Hello""}",Type Violation,Expected: N Found: S,,
```
Le fichier de sortie est au format CSV. La première ligne du fichier est un en-tête. Elle est suivie d’un registre par élément qui viole la clé d’index. Les champs de ces registres de violation sont les suivants :
+ **Table hash key** (Clé de hachage de table) – Valeur de clé de partition de l’élément dans la table.
+ **Table range key** (Clé de plage de table) – Valeur de clé de tri de l’élément dans la table.
+ **GSI hash key value** (Valeur de clé de hachage GSI) – Valeur de clé de partition de l’index secondaire global.
+ **GSI hash key violation type** (Type de violation de clé de hachage GSI) – `Type Violation` ou `Size Violation`.
+ **GSI hash key violation description** (Description de violation de clé de hachage GSI) – Cause de la violation.
+ **GSI hash key update value (FOR USER)** (Valeur de mise à jour de clé de hachage GSI (POUR UTILISATEUR)) – En mode correction, nouvelle valeur fournie par l’utilisateur pour l’attribut.
+ **GSI range key value** (Valeur de clé de plage GSI) – Valeur de clé de tri de l’index secondaire global.
+ **GSI range key violation type** (Type de violation de clé de plage GSI) – `Type Violation` ou `Size Violation`.
+ **GSI range key violation description** (Description de violation de clé de plage GSI) – Cause de la violation.
+ **GSI range key update value (FOR USER)** (Valeur de mise à jour de clé de plage GSI (POUR UTILISATEUR)) – En mode correction, nouvelle valeur fournie par l’utilisateur pour l’attribut.
+ **Delete blank attribute when updating (Y/N)** (Supprimer un attribut vide lors de la mise à jour (O/N)) – En mode correction, détermine s’il faut supprimer (Y) ou conserver (N) l’élément violant le schéma de clé dans la table, mais uniquement si l’un des champs suivants est vide :
+ `GSI Hash Key Update Value(FOR USER)`
+ `GSI Range Key Update Value(FOR USER)`
Si l’un de ces champs n’est pas vide, `Delete Blank Attribute When Updating(Y/N)` n’a aucun effet.
**Note**
Le format de sortie peut varier en fonction du fichier de configuration et des options de ligne de commande. Par exemple, si la table possède une clé primaire simple (sans clé de tri), aucun champ de clé de tri ne figure dans la sortie.
Il se peut que les registres de violation dans le fichier ne soient pas dans un ordre trié.
## Correction
Pour corriger les violations de clé d’indexation, utilisez l’outil de détection des violations avec l’option de ligne de commande `--correct`. En mode correction, l’outil de détection des violations lit le fichier d’entrée spécifié par le paramètre `correctionInputPath`. Le format de ce fichier étant le même que celui du fichier `detectionOutputPath`, vous pouvez utiliser la sortie de la détection comme entrée pour la correction.
L’outil de détection des violations offre deux options pour corriger les violations de clé d’index :
+ **Delete violations (Supprimer les violations)** – Supprimer les éléments de table qui ont des valeurs d’attribut violant le schéma de clé.
+ **Update violations (Mettre à jour les violations)** – Mettre à jour les éléments de table en remplaçant les attributs violant le schéma de clé par des valeurs ne les violant pas.
Dans les deux cas, vous pouvez utiliser le fichier de sortie du mode détection comme entrée pour le mode correction.
En poursuivant avec l’exemple `ProductCatalog`, supposons que vous voulez supprimer de la table l’élément violant le schéma de clé. Pour ce faire, vous utilisez la ligne de commande suivante.
```
$ java -jar ViolationDetector.jar --configFilePath config.txt --correct delete
```
À ce stade, vous êtes invité à confirmer si vous souhaitez supprimer les éléments violant le schéma de clé.
```
Are you sure to delete all violations on the table?y/n
y
Confirmed, will delete violations on the table...
Violation correction from file started: Reading records from file: ./gsi_violation_check.csv, will delete these records from table.
Violation correction from file finished: Violations delete: 1, Violations Update: 0
```
A présent, `ProductCatalog` et `PriceIndex` ont le même nombre d’éléments.
# Utilisation d'index secondaires globaux : Java
Vous pouvez utiliser l'API AWS SDK pour Java Document pour créer une table Amazon DynamoDB avec un ou plusieurs index secondaires globaux, décrire les index de la table et effectuer des requêtes à l'aide des index.
Voici les étapes courantes pour les opérations de table.
1. Créez une instance de la classe `DynamoDB`.
1. Fournissez les paramètres obligatoires et facultatifs pour l'opération en créant les objets de requête correspondants.
1. Appelez la méthode appropriée fournie par le client, que vous avez créée à l'étape précédente.
**Topics**
+ [Créer une table avec un index secondaire global](#GSIJavaDocumentAPI.CreateTableWithIndex)
+ [Décrire une table avec un index secondaire global](#GSIJavaDocumentAPI.DescribeTableWithIndex)
+ [Interroger un index secondaire global](#GSIJavaDocumentAPI.QueryAnIndex)
+ [Exemple : index secondaires globaux utilisant l'API du AWS SDK pour Java document](GSIJavaDocumentAPI.Example.md)
## Créer une table avec un index secondaire global
Vous pouvez créer des index secondaires globaux au moment où vous créez une table. Pour ce faire, utilisez `CreateTable` et fournissez vos spécifications pour un ou plusieurs index secondaires globaux. L'exemple de code Java suivant crée une table destinée à accueillir des données météorologiques. La clé de partition est `Location`, et la clé de tri `Date`. Un index secondaire global nommé `PrecipIndex` permet un accès rapide aux données de précipitations pour différents endroits.
Voici les étapes à suivre pour créer une table avec un index secondaire global à l'aide de l'API Document DynamoDB.
1. Créez une instance de la classe `DynamoDB`.
1. Créez une instance de la classe `CreateTableRequest` pour fournir l'information de requête.
Vous devez fournir le nom de la table, sa clé primaire et les valeurs de débit approvisionné. Pour l'index secondaire global, vous devez fournir le nom de l'index, ses paramètres de débit approvisionné, les définitions d'attribut pour la clé de tri d'index, le schéma de clé pour l'index et la projection d'attribut.
1. Appelez la méthode `createTable` en fournissant l'objet de demande comme paramètre.
L’exemple de code Java suivant illustre les tâches précédentes. Le code crée une table (`WeatherData`) avec un index secondaire global (`PrecipIndex`). La clé de partition d'index est `Date`, et la clé de tri `Precipitation`. Tous les attributs de table sont projetés sur l'index. Les utilisateurs peuvent interroger cet index afin d'obtenir des données météorologiques pour une date particulière, en triant éventuellement les données par quantité de précipitations.
`Precipitation` n'étant pas un attribut de clé pour la table, il n'est pas obligatoire. Toutefois, les éléments `WeatherData` sans `Precipitation` n'apparaissent pas dans `PrecipIndex`.
```
AmazonDynamoDB client = AmazonDynamoDBClientBuilder.standard().build();
DynamoDB dynamoDB = new DynamoDB(client);
// Attribute definitions
ArrayList attributeDefinitions = new ArrayList();
attributeDefinitions.add(new AttributeDefinition()
.withAttributeName("Location")
.withAttributeType("S"));
attributeDefinitions.add(new AttributeDefinition()
.withAttributeName("Date")
.withAttributeType("S"));
attributeDefinitions.add(new AttributeDefinition()
.withAttributeName("Precipitation")
.withAttributeType("N"));
// Table key schema
ArrayList tableKeySchema = new ArrayList();
tableKeySchema.add(new KeySchemaElement()
.withAttributeName("Location")
.withKeyType(KeyType.HASH)); //Partition key
tableKeySchema.add(new KeySchemaElement()
.withAttributeName("Date")
.withKeyType(KeyType.RANGE)); //Sort key
// PrecipIndex
GlobalSecondaryIndex precipIndex = new GlobalSecondaryIndex()
.withIndexName("PrecipIndex")
.withProvisionedThroughput(new ProvisionedThroughput()
.withReadCapacityUnits((long) 10)
.withWriteCapacityUnits((long) 1))
.withProjection(new Projection().withProjectionType(ProjectionType.ALL));
ArrayList indexKeySchema = new ArrayList();
indexKeySchema.add(new KeySchemaElement()
.withAttributeName("Date")
.withKeyType(KeyType.HASH)); //Partition key
indexKeySchema.add(new KeySchemaElement()
.withAttributeName("Precipitation")
.withKeyType(KeyType.RANGE)); //Sort key
precipIndex.setKeySchema(indexKeySchema);
CreateTableRequest createTableRequest = new CreateTableRequest()
.withTableName("WeatherData")
.withProvisionedThroughput(new ProvisionedThroughput()
.withReadCapacityUnits((long) 5)
.withWriteCapacityUnits((long) 1))
.withAttributeDefinitions(attributeDefinitions)
.withKeySchema(tableKeySchema)
.withGlobalSecondaryIndexes(precipIndex);
Table table = dynamoDB.createTable(createTableRequest);
System.out.println(table.getDescription());
```
Vous devez attendre que DynamoDB crée la table et définisse l'état de celle-ci sur `ACTIVE`. Après cela, vous pouvez commencer à insérer des éléments de données dans la table.
## Décrire une table avec un index secondaire global
Pour obtenir des informations concernant les index secondaires globaux sur une table, utilisez l'opération `DescribeTable`. Pour chaque index, vous pouvez accéder à son nom, à son schéma de clé et aux attributs projetés.
Voici les étapes à suivre pour accéder aux informations d'index secondaire global sur une table.
1. Créez une instance de la classe `DynamoDB`.
1. Créez une instance de la classe `Table` pour représenter l'index que vous souhaitez utiliser.
1. Appelez la méthode `describe` sur l'objet `Table`.
L’exemple de code Java suivant illustre les tâches précédentes.
**Example**
```
AmazonDynamoDB client = AmazonDynamoDBClientBuilder.standard().build();
DynamoDB dynamoDB = new DynamoDB(client);
Table table = dynamoDB.getTable("WeatherData");
TableDescription tableDesc = table.describe();
Iterator gsiIter = tableDesc.getGlobalSecondaryIndexes().iterator();
while (gsiIter.hasNext()) {
GlobalSecondaryIndexDescription gsiDesc = gsiIter.next();
System.out.println("Info for index "
+ gsiDesc.getIndexName() + ":");
Iterator kseIter = gsiDesc.getKeySchema().iterator();
while (kseIter.hasNext()) {
KeySchemaElement kse = kseIter.next();
System.out.printf("\t%s: %s\n", kse.getAttributeName(), kse.getKeyType());
}
Projection projection = gsiDesc.getProjection();
System.out.println("\tThe projection type is: "
+ projection.getProjectionType());
if (projection.getProjectionType().toString().equals("INCLUDE")) {
System.out.println("\t\tThe non-key projected attributes are: "
+ projection.getNonKeyAttributes());
}
}
```
## Interroger un index secondaire global
Vous pouvez utiliser l'opération `Query` sur un index secondaire global de la même manière que vous utilisez l'opération `Query` sur une table. Vous devez spécifier le nom de l'index, les critères de requête pour la clé de partition d'index et la clé de tri (le cas échéant), ainsi que les attributs que vous souhaitez renvoyer. Dans cet exemple, l'index est `PrecipIndex`. Il a une clé de partition `Date` et une clé de tri `Precipitation`. L'interrogation de l'index renvoie toutes les données météorologiques pour une date particulière, où les précipitations sont supérieures à zéro.
Voici les étapes à suivre pour interroger un index secondaire global à l'aide de l'API AWS SDK pour Java Document.
1. Créez une instance de la classe `DynamoDB`.
1. Créez une instance de la classe `Table` pour représenter l'index que vous souhaitez utiliser.
1. Créez une instance de la classe `Index` pour l'index que vous souhaitez interroger.
1. Appelez la méthode `query` sur l'objet `Index`.
Nom d'attribut `Date` est un mot réservé DynamoDB. Par conséquent, vous devez utiliser un nom d'attribut d'expression comme espace réservé dans la `KeyConditionExpression`.
L’exemple de code Java suivant illustre les tâches précédentes.
**Example**
```
AmazonDynamoDB client = AmazonDynamoDBClientBuilder.standard().build();
DynamoDB dynamoDB = new DynamoDB(client);
Table table = dynamoDB.getTable("WeatherData");
Index index = table.getIndex("PrecipIndex");
QuerySpec spec = new QuerySpec()
.withKeyConditionExpression("#d = :v_date and Precipitation = :v_precip")
.withNameMap(new NameMap()
.with("#d", "Date"))
.withValueMap(new ValueMap()
.withString(":v_date","2013-08-10")
.withNumber(":v_precip",0));
ItemCollection items = index.query(spec);
Iterator- iter = items.iterator();
while (iter.hasNext()) {
System.out.println(iter.next().toJSONPretty());
}
```
# Exemple : index secondaires globaux utilisant l'API du AWS SDK pour Java document
L'exemple de code Java suivant montre comment utiliser les index secondaires globaux. L'exemple crée une table nommée `Issues`, utilisable dans un système simple de suivi de bogues pour le développement de logiciels. La clé de partition est `IssueId`, et la clé de tri `Title`. Il y a trois index secondaires globaux sur cette table :
+ `CreateDateIndex` – La clé de partition est `CreateDate`, et la clé de tri `IssueId`. En plus des clés de table, les attributs `Description` et `Status` sont projetés dans l'index.
+ `TitleIndex` – La clé de partition est `Title`, et la clé de tri `IssueId`. Aucun attribut autre que les clés de table n'est projeté dans l'index.
+ `DueDateIndex` – La clé de partition est `DueDate` et il n'y a pas de clé de tri. Tous les attributs de table sont projetés sur l'index.
Une fois la table `Issues` créée, le programme charge la table avec des données représentant des rapports de bogues logiciels. Il interroge ensuite les données à l'aide d'index secondaires globaux. Enfin, le programme supprime la table `Issues`.
Pour step-by-step obtenir des instructions sur le test de l'exemple suivant, reportez-vous à[Exemples de code Java](CodeSamples.Java.md).
**Example**
```
package com.amazonaws.codesamples.document;
import java.util.ArrayList;
import java.util.Iterator;
import com.amazonaws.services.dynamodbv2.AmazonDynamoDB;
import com.amazonaws.services.dynamodbv2.AmazonDynamoDBClientBuilder;
import com.amazonaws.services.dynamodbv2.document.DynamoDB;
import com.amazonaws.services.dynamodbv2.document.Index;
import com.amazonaws.services.dynamodbv2.document.Item;
import com.amazonaws.services.dynamodbv2.document.ItemCollection;
import com.amazonaws.services.dynamodbv2.document.QueryOutcome;
import com.amazonaws.services.dynamodbv2.document.Table;
import com.amazonaws.services.dynamodbv2.document.spec.QuerySpec;
import com.amazonaws.services.dynamodbv2.document.utils.ValueMap;
import com.amazonaws.services.dynamodbv2.model.AttributeDefinition;
import com.amazonaws.services.dynamodbv2.model.CreateTableRequest;
import com.amazonaws.services.dynamodbv2.model.GlobalSecondaryIndex;
import com.amazonaws.services.dynamodbv2.model.KeySchemaElement;
import com.amazonaws.services.dynamodbv2.model.KeyType;
import com.amazonaws.services.dynamodbv2.model.Projection;
import com.amazonaws.services.dynamodbv2.model.ProvisionedThroughput;
public class DocumentAPIGlobalSecondaryIndexExample {
static AmazonDynamoDB client = AmazonDynamoDBClientBuilder.standard().build();
static DynamoDB dynamoDB = new DynamoDB(client);
public static String tableName = "Issues";
public static void main(String[] args) throws Exception {
createTable();
loadData();
queryIndex("CreateDateIndex");
queryIndex("TitleIndex");
queryIndex("DueDateIndex");
deleteTable(tableName);
}
public static void createTable() {
// Attribute definitions
ArrayList attributeDefinitions = new ArrayList();
attributeDefinitions.add(new AttributeDefinition().withAttributeName("IssueId").withAttributeType("S"));
attributeDefinitions.add(new AttributeDefinition().withAttributeName("Title").withAttributeType("S"));
attributeDefinitions.add(new AttributeDefinition().withAttributeName("CreateDate").withAttributeType("S"));
attributeDefinitions.add(new AttributeDefinition().withAttributeName("DueDate").withAttributeType("S"));
// Key schema for table
ArrayList tableKeySchema = new ArrayList();
tableKeySchema.add(new KeySchemaElement().withAttributeName("IssueId").withKeyType(KeyType.HASH)); // Partition
// key
tableKeySchema.add(new KeySchemaElement().withAttributeName("Title").withKeyType(KeyType.RANGE)); // Sort
// key
// Initial provisioned throughput settings for the indexes
ProvisionedThroughput ptIndex = new ProvisionedThroughput().withReadCapacityUnits(1L)
.withWriteCapacityUnits(1L);
// CreateDateIndex
GlobalSecondaryIndex createDateIndex = new GlobalSecondaryIndex().withIndexName("CreateDateIndex")
.withProvisionedThroughput(ptIndex)
.withKeySchema(new KeySchemaElement().withAttributeName("CreateDate").withKeyType(KeyType.HASH), // Partition
// key
new KeySchemaElement().withAttributeName("IssueId").withKeyType(KeyType.RANGE)) // Sort
// key
.withProjection(
new Projection().withProjectionType("INCLUDE").withNonKeyAttributes("Description", "Status"));
// TitleIndex
GlobalSecondaryIndex titleIndex = new GlobalSecondaryIndex().withIndexName("TitleIndex")
.withProvisionedThroughput(ptIndex)
.withKeySchema(new KeySchemaElement().withAttributeName("Title").withKeyType(KeyType.HASH), // Partition
// key
new KeySchemaElement().withAttributeName("IssueId").withKeyType(KeyType.RANGE)) // Sort
// key
.withProjection(new Projection().withProjectionType("KEYS_ONLY"));
// DueDateIndex
GlobalSecondaryIndex dueDateIndex = new GlobalSecondaryIndex().withIndexName("DueDateIndex")
.withProvisionedThroughput(ptIndex)
.withKeySchema(new KeySchemaElement().withAttributeName("DueDate").withKeyType(KeyType.HASH)) // Partition
// key
.withProjection(new Projection().withProjectionType("ALL"));
CreateTableRequest createTableRequest = new CreateTableRequest().withTableName(tableName)
.withProvisionedThroughput(
new ProvisionedThroughput().withReadCapacityUnits((long) 1).withWriteCapacityUnits((long) 1))
.withAttributeDefinitions(attributeDefinitions).withKeySchema(tableKeySchema)
.withGlobalSecondaryIndexes(createDateIndex, titleIndex, dueDateIndex);
System.out.println("Creating table " + tableName + "...");
dynamoDB.createTable(createTableRequest);
// Wait for table to become active
System.out.println("Waiting for " + tableName + " to become ACTIVE...");
try {
Table table = dynamoDB.getTable(tableName);
table.waitForActive();
} catch (InterruptedException e) {
e.printStackTrace();
}
}
public static void queryIndex(String indexName) {
Table table = dynamoDB.getTable(tableName);
System.out.println("\n***********************************************************\n");
System.out.print("Querying index " + indexName + "...");
Index index = table.getIndex(indexName);
ItemCollection items = null;
QuerySpec querySpec = new QuerySpec();
if (indexName == "CreateDateIndex") {
System.out.println("Issues filed on 2013-11-01");
querySpec.withKeyConditionExpression("CreateDate = :v_date and begins_with(IssueId, :v_issue)")
.withValueMap(new ValueMap().withString(":v_date", "2013-11-01").withString(":v_issue", "A-"));
items = index.query(querySpec);
} else if (indexName == "TitleIndex") {
System.out.println("Compilation errors");
querySpec.withKeyConditionExpression("Title = :v_title and begins_with(IssueId, :v_issue)")
.withValueMap(
new ValueMap().withString(":v_title", "Compilation error").withString(":v_issue", "A-"));
items = index.query(querySpec);
} else if (indexName == "DueDateIndex") {
System.out.println("Items that are due on 2013-11-30");
querySpec.withKeyConditionExpression("DueDate = :v_date")
.withValueMap(new ValueMap().withString(":v_date", "2013-11-30"));
items = index.query(querySpec);
} else {
System.out.println("\nNo valid index name provided");
return;
}
Iterator
- iterator = items.iterator();
System.out.println("Query: printing results...");
while (iterator.hasNext()) {
System.out.println(iterator.next().toJSONPretty());
}
}
public static void deleteTable(String tableName) {
System.out.println("Deleting table " + tableName + "...");
Table table = dynamoDB.getTable(tableName);
table.delete();
// Wait for table to be deleted
System.out.println("Waiting for " + tableName + " to be deleted...");
try {
table.waitForDelete();
} catch (InterruptedException e) {
e.printStackTrace();
}
}
public static void loadData() {
System.out.println("Loading data into table " + tableName + "...");
// IssueId, Title,
// Description,
// CreateDate, LastUpdateDate, DueDate,
// Priority, Status
putItem("A-101", "Compilation error", "Can't compile Project X - bad version number. What does this mean?",
"2013-11-01", "2013-11-02", "2013-11-10", 1, "Assigned");
putItem("A-102", "Can't read data file", "The main data file is missing, or the permissions are incorrect",
"2013-11-01", "2013-11-04", "2013-11-30", 2, "In progress");
putItem("A-103", "Test failure", "Functional test of Project X produces errors", "2013-11-01", "2013-11-02",
"2013-11-10", 1, "In progress");
putItem("A-104", "Compilation error", "Variable 'messageCount' was not initialized.", "2013-11-15",
"2013-11-16", "2013-11-30", 3, "Assigned");
putItem("A-105", "Network issue", "Can't ping IP address 127.0.0.1. Please fix this.", "2013-11-15",
"2013-11-16", "2013-11-19", 5, "Assigned");
}
public static void putItem(
String issueId, String title, String description, String createDate, String lastUpdateDate, String dueDate,
Integer priority, String status) {
Table table = dynamoDB.getTable(tableName);
Item item = new Item().withPrimaryKey("IssueId", issueId).withString("Title", title)
.withString("Description", description).withString("CreateDate", createDate)
.withString("LastUpdateDate", lastUpdateDate).withString("DueDate", dueDate)
.withNumber("Priority", priority).withString("Status", status);
table.putItem(item);
}
}
```
# Utilisation d'index secondaires globaux : .NET
Vous pouvez utiliser l'API de AWS SDK pour .NET bas niveau pour créer une table Amazon DynamoDB avec un ou plusieurs index secondaires globaux, décrire les index de la table et effectuer des requêtes à l'aide des index. Ces opérations mappent aux opérations DynamoDB correspondantes. Pour plus d'informations, consultez la [Référence d'API Amazon DynamoDB](https://docs.aws.amazon.com/amazondynamodb/latest/APIReference/).
Voici les étapes courantes pour les opérations de table à l'aide de l'API de bas niveau .NET.
1. Créez une instance de la classe `AmazonDynamoDBClient`.
1. Fournissez les paramètres obligatoires et facultatifs pour l'opération en créant les objets de requête correspondants.
Par exemple, créez un objet `CreateTableRequest` pour créer une table, et un objet `QueryRequest` pour interroger une table ou un index.
1. Exécutez la méthode appropriée fournie par le client, que vous avez créée à l'étape précédente.
**Topics**
+ [Créer une table avec un index secondaire global](#GSILowLevelDotNet.CreateTableWithIndex)
+ [Décrire une table avec un index secondaire global](#GSILowLevelDotNet.DescribeTableWithIndex)
+ [Interroger un index secondaire global](#GSILowLevelDotNet.QueryAnIndex)
+ [Exemple : index secondaires globaux utilisant l'API de AWS SDK pour .NET bas niveau](GSILowLevelDotNet.Example.md)
## Créer une table avec un index secondaire global
Vous pouvez créer des index secondaires globaux au moment où vous créez une table. Pour ce faire, utilisez `CreateTable` et fournissez vos spécifications pour un ou plusieurs index secondaires globaux. L'exemple de code C\$1 suivant crée une table destinée à accueillir des données météorologiques. La clé de partition est `Location`, et la clé de tri `Date`. Un index secondaire global nommé `PrecipIndex` permet un accès rapide aux données de précipitations pour différents endroits.
Voici les étapes à suivre pour créer une table avec un index secondaire global à l'aide de l'API de bas niveau .NET.
1. Créez une instance de la classe `AmazonDynamoDBClient`.
1. Créez une instance de la classe `CreateTableRequest` pour fournir l'information de requête.
Vous devez fournir le nom de la table, sa clé primaire et les valeurs de débit approvisionné. Pour l'index secondaire global, vous devez fournir le nom de l'index, ses paramètres de débit approvisionné, les définitions d'attribut pour la clé de tri d'index, le schéma de clé pour l'index et la projection d'attribut.
1. Exécutez la méthode `CreateTable` en fournissant l'objet de demande comme paramètre.
L’exemple de code C\$1 suivant illustre les étapes précédentes. Le code crée une table (`WeatherData`) avec un index secondaire global (`PrecipIndex`). La clé de partition d'index est `Date`, et la clé de tri `Precipitation`. Tous les attributs de table sont projetés sur l'index. Les utilisateurs peuvent interroger cet index afin d'obtenir des données météorologiques pour une date particulière, en triant éventuellement les données par quantité de précipitations.
`Precipitation` n'étant pas un attribut de clé pour la table, il n'est pas obligatoire. Toutefois, les éléments `WeatherData` sans `Precipitation` n'apparaissent pas dans `PrecipIndex`.
```
client = new AmazonDynamoDBClient();
string tableName = "WeatherData";
// Attribute definitions
var attributeDefinitions = new List()
{
{new AttributeDefinition{
AttributeName = "Location",
AttributeType = "S"}},
{new AttributeDefinition{
AttributeName = "Date",
AttributeType = "S"}},
{new AttributeDefinition(){
AttributeName = "Precipitation",
AttributeType = "N"}
}
};
// Table key schema
var tableKeySchema = new List()
{
{new KeySchemaElement {
AttributeName = "Location",
KeyType = "HASH"}}, //Partition key
{new KeySchemaElement {
AttributeName = "Date",
KeyType = "RANGE"} //Sort key
}
};
// PrecipIndex
var precipIndex = new GlobalSecondaryIndex
{
IndexName = "PrecipIndex",
ProvisionedThroughput = new ProvisionedThroughput
{
ReadCapacityUnits = (long)10,
WriteCapacityUnits = (long)1
},
Projection = new Projection { ProjectionType = "ALL" }
};
var indexKeySchema = new List {
{new KeySchemaElement { AttributeName = "Date", KeyType = "HASH"}}, //Partition key
{new KeySchemaElement{AttributeName = "Precipitation",KeyType = "RANGE"}} //Sort key
};
precipIndex.KeySchema = indexKeySchema;
CreateTableRequest createTableRequest = new CreateTableRequest
{
TableName = tableName,
ProvisionedThroughput = new ProvisionedThroughput
{
ReadCapacityUnits = (long)5,
WriteCapacityUnits = (long)1
},
AttributeDefinitions = attributeDefinitions,
KeySchema = tableKeySchema,
GlobalSecondaryIndexes = { precipIndex }
};
CreateTableResponse response = client.CreateTable(createTableRequest);
Console.WriteLine(response.CreateTableResult.TableDescription.TableName);
Console.WriteLine(response.CreateTableResult.TableDescription.TableStatus);
```
Vous devez attendre que DynamoDB crée la table et définisse l'état de celle-ci sur `ACTIVE`. Après cela, vous pouvez commencer à insérer des éléments de données dans la table.
## Décrire une table avec un index secondaire global
Pour obtenir des informations concernant les index secondaires globaux sur une table, utilisez l'opération `DescribeTable`. Pour chaque index, vous pouvez accéder à son nom, à son schéma de clé et aux attributs projetés.
Voici les étapes à suivre pour accéder aux informations d'index secondaire global pour une table à l'aide de l'API de bas niveau .NET.
1. Créez une instance de la classe `AmazonDynamoDBClient`.
1. Exécutez la méthode `describeTable` en fournissant l'objet de demande comme paramètre.
Créez une instance de la classe `DescribeTableRequest` pour fournir l'information de requête. Vous devez fournir le nom de la table.
L’exemple de code C\$1 suivant illustre les étapes précédentes.
**Example**
```
client = new AmazonDynamoDBClient();
string tableName = "WeatherData";
DescribeTableResponse response = client.DescribeTable(new DescribeTableRequest { TableName = tableName});
List globalSecondaryIndexes =
response.DescribeTableResult.Table.GlobalSecondaryIndexes;
// This code snippet will work for multiple indexes, even though
// there is only one index in this example.
foreach (GlobalSecondaryIndexDescription gsiDescription in globalSecondaryIndexes) {
Console.WriteLine("Info for index " + gsiDescription.IndexName + ":");
foreach (KeySchemaElement kse in gsiDescription.KeySchema) {
Console.WriteLine("\t" + kse.AttributeName + ": key type is " + kse.KeyType);
}
Projection projection = gsiDescription.Projection;
Console.WriteLine("\tThe projection type is: " + projection.ProjectionType);
if (projection.ProjectionType.ToString().Equals("INCLUDE")) {
Console.WriteLine("\t\tThe non-key projected attributes are: "
+ projection.NonKeyAttributes);
}
}
```
## Interroger un index secondaire global
Vous pouvez utiliser l'opération `Query` sur un index secondaire global de la même manière que vous utilisez l'opération `Query` sur une table. Vous devez spécifier le nom de l'index, les critères de requête pour la clé de partition d'index et la clé de tri (le cas échéant), ainsi que les attributs que vous souhaitez renvoyer. Dans cet exemple, l'index est `PrecipIndex`. Il a une clé de partition `Date` et une clé de tri `Precipitation`. L'interrogation de l'index renvoie toutes les données météorologiques pour une date particulière, où les précipitations sont supérieures à zéro.
Voici les étapes à suivre pour interroger un index secondaire global à l'aide de l'API de bas niveau .NET.
1. Créez une instance de la classe `AmazonDynamoDBClient`.
1. Créez une instance de la classe `QueryRequest` pour fournir l'information de requête.
1. Exécutez la méthode `query` en fournissant l'objet de demande comme paramètre.
Nom d'attribut `Date` est un mot réservé DynamoDB. Par conséquent, vous devez utiliser un nom d'attribut d'expression comme espace réservé dans la `KeyConditionExpression`.
L’exemple de code C\$1 suivant illustre les étapes précédentes.
**Example**
```
client = new AmazonDynamoDBClient();
QueryRequest queryRequest = new QueryRequest
{
TableName = "WeatherData",
IndexName = "PrecipIndex",
KeyConditionExpression = "#dt = :v_date and Precipitation > :v_precip",
ExpressionAttributeNames = new Dictionary {
{"#dt", "Date"}
},
ExpressionAttributeValues = new Dictionary {
{":v_date", new AttributeValue { S = "2013-08-01" }},
{":v_precip", new AttributeValue { N = "0" }}
},
ScanIndexForward = true
};
var result = client.Query(queryRequest);
var items = result.Items;
foreach (var currentItem in items)
{
foreach (string attr in currentItem.Keys)
{
Console.Write(attr + "---> ");
if (attr == "Precipitation")
{
Console.WriteLine(currentItem[attr].N);
}
else
{
Console.WriteLine(currentItem[attr].S);
}
}
Console.WriteLine();
}
```
# Exemple : index secondaires globaux utilisant l'API de AWS SDK pour .NET bas niveau
L'exemple de code C\$1 suivant montre comment utiliser des index secondaires globaux. L'exemple crée une table nommée `Issues`, utilisable dans un système simple de suivi de bogues pour le développement de logiciels. La clé de partition est `IssueId`, et la clé de tri `Title`. Il y a trois index secondaires globaux sur cette table :
+ `CreateDateIndex` – La clé de partition est `CreateDate`, et la clé de tri `IssueId`. En plus des clés de table, les attributs `Description` et `Status` sont projetés dans l'index.
+ `TitleIndex` – La clé de partition est `Title`, et la clé de tri `IssueId`. Aucun attribut autre que les clés de table n'est projeté dans l'index.
+ `DueDateIndex` – La clé de partition est `DueDate` et il n'y a pas de clé de tri. Tous les attributs de table sont projetés sur l'index.
Une fois la table `Issues` créée, le programme charge la table avec des données représentant des rapports de bogues logiciels. Il interroge ensuite les données à l'aide d'index secondaires globaux. Enfin, le programme supprime la table `Issues`.
Pour step-by-step obtenir des instructions sur le test de l'échantillon suivant, reportez-vous à[Exemples de code .NET](CodeSamples.DotNet.md).
**Example**
```
using System;
using System.Collections.Generic;
using System.Linq;
using Amazon.DynamoDBv2;
using Amazon.DynamoDBv2.DataModel;
using Amazon.DynamoDBv2.DocumentModel;
using Amazon.DynamoDBv2.Model;
using Amazon.Runtime;
using Amazon.SecurityToken;
namespace com.amazonaws.codesamples
{
class LowLevelGlobalSecondaryIndexExample
{
private static AmazonDynamoDBClient client = new AmazonDynamoDBClient();
public static String tableName = "Issues";
public static void Main(string[] args)
{
CreateTable();
LoadData();
QueryIndex("CreateDateIndex");
QueryIndex("TitleIndex");
QueryIndex("DueDateIndex");
DeleteTable(tableName);
Console.WriteLine("To continue, press enter");
Console.Read();
}
private static void CreateTable()
{
// Attribute definitions
var attributeDefinitions = new List()
{
{new AttributeDefinition {
AttributeName = "IssueId", AttributeType = "S"
}},
{new AttributeDefinition {
AttributeName = "Title", AttributeType = "S"
}},
{new AttributeDefinition {
AttributeName = "CreateDate", AttributeType = "S"
}},
{new AttributeDefinition {
AttributeName = "DueDate", AttributeType = "S"
}}
};
// Key schema for table
var tableKeySchema = new List() {
{
new KeySchemaElement {
AttributeName= "IssueId",
KeyType = "HASH" //Partition key
}
},
{
new KeySchemaElement {
AttributeName = "Title",
KeyType = "RANGE" //Sort key
}
}
};
// Initial provisioned throughput settings for the indexes
var ptIndex = new ProvisionedThroughput
{
ReadCapacityUnits = 1L,
WriteCapacityUnits = 1L
};
// CreateDateIndex
var createDateIndex = new GlobalSecondaryIndex()
{
IndexName = "CreateDateIndex",
ProvisionedThroughput = ptIndex,
KeySchema = {
new KeySchemaElement {
AttributeName = "CreateDate", KeyType = "HASH" //Partition key
},
new KeySchemaElement {
AttributeName = "IssueId", KeyType = "RANGE" //Sort key
}
},
Projection = new Projection
{
ProjectionType = "INCLUDE",
NonKeyAttributes = {
"Description", "Status"
}
}
};
// TitleIndex
var titleIndex = new GlobalSecondaryIndex()
{
IndexName = "TitleIndex",
ProvisionedThroughput = ptIndex,
KeySchema = {
new KeySchemaElement {
AttributeName = "Title", KeyType = "HASH" //Partition key
},
new KeySchemaElement {
AttributeName = "IssueId", KeyType = "RANGE" //Sort key
}
},
Projection = new Projection
{
ProjectionType = "KEYS_ONLY"
}
};
// DueDateIndex
var dueDateIndex = new GlobalSecondaryIndex()
{
IndexName = "DueDateIndex",
ProvisionedThroughput = ptIndex,
KeySchema = {
new KeySchemaElement {
AttributeName = "DueDate",
KeyType = "HASH" //Partition key
}
},
Projection = new Projection
{
ProjectionType = "ALL"
}
};
var createTableRequest = new CreateTableRequest
{
TableName = tableName,
ProvisionedThroughput = new ProvisionedThroughput
{
ReadCapacityUnits = (long)1,
WriteCapacityUnits = (long)1
},
AttributeDefinitions = attributeDefinitions,
KeySchema = tableKeySchema,
GlobalSecondaryIndexes = {
createDateIndex, titleIndex, dueDateIndex
}
};
Console.WriteLine("Creating table " + tableName + "...");
client.CreateTable(createTableRequest);
WaitUntilTableReady(tableName);
}
private static void LoadData()
{
Console.WriteLine("Loading data into table " + tableName + "...");
// IssueId, Title,
// Description,
// CreateDate, LastUpdateDate, DueDate,
// Priority, Status
putItem("A-101", "Compilation error",
"Can't compile Project X - bad version number. What does this mean?",
"2013-11-01", "2013-11-02", "2013-11-10",
1, "Assigned");
putItem("A-102", "Can't read data file",
"The main data file is missing, or the permissions are incorrect",
"2013-11-01", "2013-11-04", "2013-11-30",
2, "In progress");
putItem("A-103", "Test failure",
"Functional test of Project X produces errors",
"2013-11-01", "2013-11-02", "2013-11-10",
1, "In progress");
putItem("A-104", "Compilation error",
"Variable 'messageCount' was not initialized.",
"2013-11-15", "2013-11-16", "2013-11-30",
3, "Assigned");
putItem("A-105", "Network issue",
"Can't ping IP address 127.0.0.1. Please fix this.",
"2013-11-15", "2013-11-16", "2013-11-19",
5, "Assigned");
}
private static void putItem(
String issueId, String title,
String description,
String createDate, String lastUpdateDate, String dueDate,
Int32 priority, String status)
{
Dictionary item = new Dictionary();
item.Add("IssueId", new AttributeValue
{
S = issueId
});
item.Add("Title", new AttributeValue
{
S = title
});
item.Add("Description", new AttributeValue
{
S = description
});
item.Add("CreateDate", new AttributeValue
{
S = createDate
});
item.Add("LastUpdateDate", new AttributeValue
{
S = lastUpdateDate
});
item.Add("DueDate", new AttributeValue
{
S = dueDate
});
item.Add("Priority", new AttributeValue
{
N = priority.ToString()
});
item.Add("Status", new AttributeValue
{
S = status
});
try
{
client.PutItem(new PutItemRequest
{
TableName = tableName,
Item = item
});
}
catch (Exception e)
{
Console.WriteLine(e.ToString());
}
}
private static void QueryIndex(string indexName)
{
Console.WriteLine
("\n***********************************************************\n");
Console.WriteLine("Querying index " + indexName + "...");
QueryRequest queryRequest = new QueryRequest
{
TableName = tableName,
IndexName = indexName,
ScanIndexForward = true
};
String keyConditionExpression;
Dictionary expressionAttributeValues = new Dictionary();
if (indexName == "CreateDateIndex")
{
Console.WriteLine("Issues filed on 2013-11-01\n");
keyConditionExpression = "CreateDate = :v_date and begins_with(IssueId, :v_issue)";
expressionAttributeValues.Add(":v_date", new AttributeValue
{
S = "2013-11-01"
});
expressionAttributeValues.Add(":v_issue", new AttributeValue
{
S = "A-"
});
}
else if (indexName == "TitleIndex")
{
Console.WriteLine("Compilation errors\n");
keyConditionExpression = "Title = :v_title and begins_with(IssueId, :v_issue)";
expressionAttributeValues.Add(":v_title", new AttributeValue
{
S = "Compilation error"
});
expressionAttributeValues.Add(":v_issue", new AttributeValue
{
S = "A-"
});
// Select
queryRequest.Select = "ALL_PROJECTED_ATTRIBUTES";
}
else if (indexName == "DueDateIndex")
{
Console.WriteLine("Items that are due on 2013-11-30\n");
keyConditionExpression = "DueDate = :v_date";
expressionAttributeValues.Add(":v_date", new AttributeValue
{
S = "2013-11-30"
});
// Select
queryRequest.Select = "ALL_PROJECTED_ATTRIBUTES";
}
else
{
Console.WriteLine("\nNo valid index name provided");
return;
}
queryRequest.KeyConditionExpression = keyConditionExpression;
queryRequest.ExpressionAttributeValues = expressionAttributeValues;
var result = client.Query(queryRequest);
var items = result.Items;
foreach (var currentItem in items)
{
foreach (string attr in currentItem.Keys)
{
if (attr == "Priority")
{
Console.WriteLine(attr + "---> " + currentItem[attr].N);
}
else
{
Console.WriteLine(attr + "---> " + currentItem[attr].S);
}
}
Console.WriteLine();
}
}
private static void DeleteTable(string tableName)
{
Console.WriteLine("Deleting table " + tableName + "...");
client.DeleteTable(new DeleteTableRequest
{
TableName = tableName
});
WaitForTableToBeDeleted(tableName);
}
private static void WaitUntilTableReady(string tableName)
{
string status = null;
// Let us wait until table is created. Call DescribeTable.
do
{
System.Threading.Thread.Sleep(5000); // Wait 5 seconds.
try
{
var res = client.DescribeTable(new DescribeTableRequest
{
TableName = tableName
});
Console.WriteLine("Table name: {0}, status: {1}",
res.Table.TableName,
res.Table.TableStatus);
status = res.Table.TableStatus;
}
catch (ResourceNotFoundException)
{
// DescribeTable is eventually consistent. So you might
// get resource not found. So we handle the potential exception.
}
} while (status != "ACTIVE");
}
private static void WaitForTableToBeDeleted(string tableName)
{
bool tablePresent = true;
while (tablePresent)
{
System.Threading.Thread.Sleep(5000); // Wait 5 seconds.
try
{
var res = client.DescribeTable(new DescribeTableRequest
{
TableName = tableName
});
Console.WriteLine("Table name: {0}, status: {1}",
res.Table.TableName,
res.Table.TableStatus);
}
catch (ResourceNotFoundException)
{
tablePresent = false;
}
}
}
}
}
```
# Gestion des index secondaires globaux dans DynamoDB à l’aide de l’AWS CLI
Vous pouvez utiliser l’AWS CLI pour créer une table Amazon DynamoDB avec un ou plusieurs index secondaires globaux, décrire les index sur la table, et effectuer des requêtes à l’aide des index.
**Topics**
+ [Créer une table avec un index secondaire global](#GCICli.CreateTableWithIndex)
+ [Ajouter un index secondaire global à une table existante](#GCICli.CreateIndexAfterTable)
+ [Décrire une table avec un index secondaire global](#GCICli.DescribeTableWithIndex)
+ [Interroger un index secondaire global](#GCICli.QueryAnIndex)
## Créer une table avec un index secondaire global
Vous pouvez créer des index secondaires globaux au moment où vous créez une table. Pour ce faire, utilisez le paramètre `create-table` et fournissez vos spécifications pour un ou plusieurs index secondaires globaux. L’exemple suivant crée une table nommée `GameScores` avec un index secondaire global nommé `GameTitleIndex`. La table de base a une clé de partition `UserId` et une clé de tri `GameTitle`, vous permettant de trouver efficacement le meilleur score d’un utilisateur pour un jeu spécifique, tandis que l’index secondaire global (GSI) a une clé de partition `GameTitle` et une clé de tri `TopScore`, vous permettant de trouver rapidement le score le plus élevé pour un jeu particulier.
```
aws dynamodb create-table \
--table-name GameScores \
--attribute-definitions AttributeName=UserId,AttributeType=S \
AttributeName=GameTitle,AttributeType=S \
AttributeName=TopScore,AttributeType=N \
--key-schema AttributeName=UserId,KeyType=HASH \
AttributeName=GameTitle,KeyType=RANGE \
--provisioned-throughput ReadCapacityUnits=10,WriteCapacityUnits=5 \
--global-secondary-indexes \
"[
{
\"IndexName\": \"GameTitleIndex\",
\"KeySchema\": [{\"AttributeName\":\"GameTitle\",\"KeyType\":\"HASH\"},
{\"AttributeName\":\"TopScore\",\"KeyType\":\"RANGE\"}],
\"Projection\":{
\"ProjectionType\":\"INCLUDE\",
\"NonKeyAttributes\":[\"UserId\"]
},
\"ProvisionedThroughput\": {
\"ReadCapacityUnits\": 10,
\"WriteCapacityUnits\": 5
}
}
]"
```
Vous devez attendre que DynamoDB crée la table et définisse l’état de celle-ci sur `ACTIVE`. Après cela, vous pouvez commencer à insérer des éléments de données dans la table. Vous pouvez utiliser la commande [describe-table](https://docs.aws.amazon.com/cli/latest/reference/dynamodb/describe-table.html) pour déterminer l’état de la création de table.
## Ajouter un index secondaire global à une table existante
Vous pouvez également ajouter ou modifier des index secondaires globaux après la création de la table. Pour ce faire, utilisez le paramètre `update-table` et fournissez vos spécifications pour un ou plusieurs index secondaires globaux. L’exemple suivant utilise le même schéma que l’exemple précédent, mais part du principe que la table a déjà été créée et que nous ajoutons le GSI par la suite.
```
aws dynamodb update-table \
--table-name GameScores \
--attribute-definitions AttributeName=TopScore,AttributeType=N \
--global-secondary-index-updates \
"[
{
\"Create\": {
\"IndexName\": \"GameTitleIndex\",
\"KeySchema\": [{\"AttributeName\":\"GameTitle\",\"KeyType\":\"HASH\"},
{\"AttributeName\":\"TopScore\",\"KeyType\":\"RANGE\"}],
\"Projection\":{
\"ProjectionType\":\"INCLUDE\",
\"NonKeyAttributes\":[\"UserId\"]
}
}
}
]"
```
## Décrire une table avec un index secondaire global
Pour obtenir des informations concernant les index secondaires globaux sur une table, utilisez le paramètre `describe-table`. Pour chaque index, vous pouvez accéder à son nom, à son schéma de clé et aux attributs projetés.
```
aws dynamodb describe-table --table-name GameScores
```
## Interroger un index secondaire global
Vous pouvez utiliser l’opération `query` sur un index secondaire global de la même manière que vous utilisez l’opération `query` sur une table. Vous devez spécifier le nom d’index, les critères de requête pour la clé de tri d’index et les attributs que vous souhaitez renvoyer. Dans cet exemple, l’index est `GameTitleIndex` et la clé de tri d’index est `GameTitle`.
Les seuls attributs renvoyés sont ceux qui ont été projetés dans l’index. Vous pourriez également modifier cette requête pour sélectionner des attributs autres que de clé, mais cela nécessiterait une activité d’extraction de table relativement coûteuse. Pour plus d’informations sur les extractions de table, consultez [Projections d’attribut](GSI.md#GSI.Projections).
```
aws dynamodb query --table-name GameScores\
--index-name GameTitleIndex \
--key-condition-expression "GameTitle = :v_game" \
--expression-attribute-values '{":v_game":{"S":"Alien Adventure"} }'
```
# Index locaux secondaires
Certaines applications doivent uniquement interroger les données à l’aide de la clé primaire de la table de base. Cependant, il peut y avoir des situations où une clé de tri alternative serait utile. Pour donner à votre application un choix de clés de tri, vous pouvez créer un ou plusieurs index secondaires locaux sur une table Amazon DynamoDB, et émettre des demandes `Query` ou `Scan` par rapport à ces index.
**Topics**
+ [Étape 6 : Utilisation d’un index secondaire local](#LSI.Scenario)
+ [Projections d’attribut](#LSI.Projections)
+ [Création d’un index secondaire local](#LSI.Creating)
+ [Lecture de données à partir d’un index secondaire local](#LSI.Reading)
+ [Écritures d’élément et index secondaires locaux](#LSI.Writes)
+ [Considérations relatives au débit alloué pour les index secondaires locaux](#LSI.ThroughputConsiderations)
+ [Considérations relatives au stockage pour les index secondaires locaux](#LSI.StorageConsiderations)
+ [Collections d’articles dans les index secondaires locaux](#LSI.ItemCollections)
+ [Utilisation d'index secondaires locaux : Java](LSIJavaDocumentAPI.md)
+ [Utilisation d'index secondaires locaux : .NET](LSILowLevelDotNet.md)
+ [Utilisation d’index secondaires locaux dans la AWS CLI de DynamoDB](LCICli.md)
## Étape 6 : Utilisation d’un index secondaire local
À titre d’exemple, considérez la table `Thread`. Cette table est utile pour une application telle que les [Forums de discussion AWS](https://forums.aws.amazon.com/). Le schéma suivant illustre la façon dont les éléments de la table seront organisés. (Tous les attributs ne sont pas affichés.)
![\[Table d’unités d’exécution contenant une liste de noms de forum, des sujets, une heure de dernière publication et un nombre de réponses.\]](http://docs.aws.amazon.com/fr_fr/amazondynamodb/latest/developerguide/images/LSI_01.png)
DynamoDB stocke tous les éléments ayant la même valeur de clé de partition de manière continue. Dans cet exemple, étant donné un `ForumName` particulier, une opération `Query` pourrait localiser immédiatement toutes les unités d’exécution pour ce forum. Dans un groupe d’éléments ayant la même valeur de clé de partition, les éléments sont triés par valeur de clé de tri. Si la clé de tri (`Subject`) est également fournie dans la requête, DynamoDB peut réduire les résultats renvoyés, par exemple, en renvoyant toutes les unités d’exécution du forum « S3 » qui ont un `Subject` commençant par la lettre « a ».
Certaines demandes peuvent nécessiter des modèles d’accès aux données plus complexes. Par exemple :
+ Quelles unités d’exécution de forum obtiennent le plus de vues et de réponses ?
+ Quelle unité d’exécution dans un forum particulier a le plus grand nombre de messages ?
+ Combien d’unités d’exécution ont été publiées dans un forum particulier au cours d’une période donnée ?
Pour répondre à ces questions, l’action `Query` ne serait pas suffisante. Au lieu de cela, vous devriez effectuer une opération `Scan` sur la table toute entière. Pour une table contenant des millions d’éléments, cette opération utiliserait une grande quantité de débit de lecture approvisionné et prendrait beaucoup de temps.
En revanche, vous pouvez spécifier un ou plusieurs index secondaires locaux sur des attributs autres que de clé, tels que `Replies` ou `LastPostDateTime`.
A *index secondaire local* gère une clé de tri alternative pour une valeur de clé de partition donnée. Un index secondaire local contient également une copie de tout ou partie des attributs de sa table de base. Vous spécifiez quels attributs sont projetés dans l’index secondaire local lorsque vous créez la table. Les données dans un index secondaire local sont organisées avec la même clé de partition que la table de base, mais une clé de tri différente. Cela vous permet d’accéder efficacement aux éléments de données dans cette dimension différente. Pour bénéficier d’une plus grande flexibilité de requête ou d’analyse, vous pouvez créer jusqu’à cinq index secondaires locaux par table.
Supposons qu’une application ait besoin de trouver toutes les discussions publiées au cours des trois derniers mois dans un forum particulier. A défaut d’index secondaire local, l’application devrait effectuer une opération `Scan` sur la table `Thread` toute entière, et écarter les publications ne d’inscrivant pas dans la période spécifiée. Avec un index secondaire local, une opération `Query` pourrait utiliser `LastPostDateTime` comme clé de tri et trouver les données rapidement.
Le diagramme suivant illustre un index secondaire local nommé `LastPostIndex`. Notez que la clé de partition est la même que celle de la table `Thread`, mais la clé de tri est `LastPostDateTime`.
![\[LastPostIndex tableau contenant une liste des noms des forums, des sujets et de l'heure du dernier message.\]](http://docs.aws.amazon.com/fr_fr/amazondynamodb/latest/developerguide/images/LSI_02.png)
Chaque index secondaire local doit remplir les conditions suivantes :
+ La clé de partition est la même que celle de sa table de base.
+ La clé de tri se compose exactement d’un attribut scalaire.
+ La clé de tri de la table de base est projetée dans l’index, où elle agit comme un attribut autre que de clé.
Dans cet exemple, la clé de partition est `ForumName` et la clé de tri de l’index secondaire local est `LastPostDateTime`. En outre, la valeur de clé de tri de la table de base (dans cet exemple, `Subject`) est projetée dans l’index, mais ne fait pas partie de la clé d’index. Si une application a besoin d’une liste basée sur `ForumName` et `LastPostDateTime`, elle peut émettre une demande `Query` par rapport à `LastPostIndex`. Les résultats de la requête sont triés par `LastPostDateTime`, et peuvent être renvoyés dans un ordre croissant ou décroissant. La requête peut également appliquer des conditions de clé, telles que renvoyer uniquement les éléments qui ont une valeur `LastPostDateTime` s’inscrivant dans une période particulière.
Chaque index secondaire local contient automatiquement les clés de partition et de tri de sa table de base. Vous pouvez éventuellement projeter des attributs autres que de clé dans l’index. Lorsque vous interrogez l’index, DynamoDB peut extraire ces attributs projetés de façon efficace. Quand vous interrogez un index secondaire local, la requête peut également extraire des attributs qui ne sont *pas* projetés dans l’index. DynamoDB extrait automatiquement ces attributs de la table de base, mais moyennant une latence et des coûts de débit approvisionné plus élevés.
Pour tout index secondaire local, vous pouvez stocker jusqu’à 10 Go de données par valeur de clé de partition. Cette figure inclut tous les éléments de la table de base, ainsi que tous les éléments des index, qui ont la même valeur de clé de partition. Pour de plus amples informations, veuillez consulter [Collections d’articles dans les index secondaires locaux](#LSI.ItemCollections).
## Projections d’attribut
Avec `LastPostIndex`, une application pourrait utiliser `ForumName` et `LastPostDateTime` en tant que critères de requête. Toutefois, pour récupérer des attributs supplémentaires, DynamoDB doit effectuer des opérations de lecture supplémentaires par rapport à la table `Thread`. Ces lectures supplémentaires appelées *extractions* peuvent augmenter le volume total de débit approvisionné requis pour une requête.
Supposons que vous souhaitiez remplir une page Web avec une liste de tous les sujets de « S3 » et le nombre de réponses pour chaque fil, triés selon la dernière réponse en date/time commençant par la réponse la plus récente. Pour remplir cette liste, vous avez besoin des attributs suivants :
+ `Subject`
+ `Replies`
+ `LastPostDateTime`
La manière la plus efficace d’interroger ces données et d’éviter les opérations d’extraction serait de projeter l’attribut `Replies` de la table vers l’index secondaire local, comme illustré dans ce diagramme.
![\[LastPostIndex tableau contenant une liste des noms des forums, des heures des derniers messages, des sujets et des réponses.\]](http://docs.aws.amazon.com/fr_fr/amazondynamodb/latest/developerguide/images/LSI_03.png)
Une *projection* est l’ensemble d’attributs copié à partir d’une table dans un index secondaire. Les clés de partition et de tri de la table sont toujours projetées dans l’index. Vous pouvez projeter d’autres attributs en fonction des exigences de requête de votre application. Lorsque vous interrogez un index, Amazon DynamoDB peut accéder à n’importe quel attribut dans la projection, comme s’il se trouvait dans une table.
Lorsque vous créez un index secondaire, vous devez spécifier les attributs qui seront projetés dans celui-ci. Pour cela, DynamoDB propose trois options :
+ *KEYS\$1ONLY* – Chaque élément de l’index se compose uniquement des valeurs de clé de partition et de tri de la table, ainsi que des valeurs de clé d’index. L’option `KEYS_ONLY` produit l’index secondaire le plus petit possible.
+ *INCLUDE* – En plus des attributs décrits dans `KEYS_ONLY`, l’index secondaire inclut des attributs autres que de clé, que vous spécifiez.
+ *ALL* – L’index secondaire inclut tous les attributs de la table source. Toutes les données de la table étant dupliquées dans l’index, une projection `ALL` produit l’index secondaire le plus grand possible.
Dans le diagramme précédent, l’attribut autre que de clé `Replies` est projeté dans `LastPostIndex`. Une application peut interroger `LastPostIndex` au lieu de la table `Thread` toute entière pour remplir une page avec des sujets (`Subject`), réponses (`Replies`) et horodatages de dernière publication `LastPostDateTime`. Si d’autres attributs autres que de clé sont demandés, DynamoDB doit les extraire de la table `Thread`.
Du point de vue d’une application, l’extraction d’attributs supplémentaires à partir de la table de base est automatique et transparente. Il n’est donc pas nécessaire de réécrire une logique d’application. Cependant, une telle récupération peut réduire considérablement l’avantage en termes de performances de l’utilisation d’un index secondaire local.
Lorsque vous choisissez les attributs à projeter sur un index secondaire local, vous devez prendre en compte le compromis entre les coûts de débit approvisionné et les coûts de stockage :
+ Si vous n’avez besoin d’accéder qu’à quelques attributs avec la plus faible latence possible, envisagez de projeter ces seuls attributs dans un index secondaire local. Plus l’index est petit, moins les coûts d’écriture et de stockage sont élevés. S’il existe des attributs que vous devez extraire occasionnellement, le coût du débit approvisionné risque d’être supérieur au coût à plus long terme du stockage de ces attributs.
+ Si votre application accède fréquemment à certains attributs autres que de clé, vous devez envisager de projeter ces attributs dans un index secondaire local. Les coûts de stockage supplémentaires de l’index secondaire local compensent le coût d’exécution d’analyses de table fréquentes.
+ Si vous avez besoin d’accéder fréquemment à la plupart des attributs autres que de clé, vous pouvez projeter ceux-ci (voire la table de base toute entière) dans un index secondaire local. Vous bénéficiez ainsi d’une flexibilité maximale et d’une consommation de débit approvisionné minimale, car aucune extraction n’est requise. Cependant, vos coûts de stockage augmentent, voire doublent, si vous projetez tous les attributs.
+ Si votre application doit interroger une table peu fréquemment, mais doit effectuer un grand nombre d’écritures ou de mises à jour de données dans la table, pensez à projeter *KEYS\$1ONLY*. L’index secondaire local sera d’une taille minimum, mais continuera d’être disponible chaque fois que ce sera nécessaire pour une activité de requête.
## Création d’un index secondaire local
Pour créer un ou plusieurs index secondaires locaux sur une table, utilisez le paramètre `LocalSecondaryIndexes` de l’opération `CreateTable`. Des index secondaires locaux sur une table sont créés lors de la création de celle-ci. Lorsque vous supprimez une table, tous les index secondaires globaux sur celle-ci sont également supprimés.
Vous devez spécifier un attribut autre que de clé pour agir en tant que clé de tri de l’index secondaire local. L’attribut que vous choisissez doit être un scalaire `String`, `Number` ou `Binary`. Les autres types scalaires, types de document et types d’ensemble ne sont pas autorisés. Pour obtenir la liste complète des types de données, consultez [Types de données](HowItWorks.NamingRulesDataTypes.md#HowItWorks.DataTypes).
**Important**
Pour les tables avec des index secondaires locaux, il existe une limite de taille de 10 Go par valeur de clé de partition. Une table avec des index secondaires locaux peut stocker n’importe quel nombre d’éléments, à condition qu’aucune valeur de clé de partition n’ait une taille supérieure à 10 Go. Pour de plus amples informations, veuillez consulter [Taille limite de collection d’éléments](#LSI.ItemCollections.SizeLimit).
Vous pouvez projeter des attributs de tout type de données dans un index secondaire local. Celui-ci inclut des scalaires, des documents et des ensembles. Pour obtenir la liste complète des types de données, consultez [Types de données](HowItWorks.NamingRulesDataTypes.md#HowItWorks.DataTypes).
## Lecture de données à partir d’un index secondaire local
Vous pouvez extraire des éléments d’un index secondaire local à l’aide des opérations `Query` et `Scan`. Vous ne pouvez pas utiliser les opérations `GetItem` et `BatchGetItem` sur un index secondaire local.
### Interrogation d’un index secondaire local
Dans une table DynamoDB, les valeurs combinées des clés de partition et de tri pour chaque élément doivent être uniques. Cependant, dans un index secondaire local, la valeur de clé de tri n’a pas besoin d’être unique pour une valeur de clé de partition donnée. Si plusieurs éléments dans l’index secondaire local ont la même valeur de clé de tri, une opération `Query` renvoie tous les éléments ayant la même valeur de clé de partition. Dans la réponse, les éléments correspondants ne sont pas renvoyés dans un ordre particulier.
Vous pouvez interroger un index secondaire local en utilisant des lectures éventuellement ou fortement cohérentes. Pour spécifier le type de cohérence que vous souhaitez, utilisez le paramètre `ConsistentRead` de l’opération `Query`. Une lecture fortement cohérente d’un index secondaire local renvoie toujours les dernières valeurs mises à jour. Si la requête doit extraire des attributs supplémentaires de la table de base, ces attributs sont cohérents par rapport à l’index.
**Example**
Considérez les données suivantes renvoyées par une opération `Query` qui demande des données des unités d’exécution de discussion dans un forum particulier.
```
{
"TableName": "Thread",
"IndexName": "LastPostIndex",
"ConsistentRead": false,
"ProjectionExpression": "Subject, LastPostDateTime, Replies, Tags",
"KeyConditionExpression":
"ForumName = :v_forum and LastPostDateTime between :v_start and :v_end",
"ExpressionAttributeValues": {
":v_start": {"S": "2015-08-31T00:00:00.000Z"},
":v_end": {"S": "2015-11-31T00:00:00.000Z"},
":v_forum": {"S": "EC2"}
}
}
```
Dans cette requête :
+ DynamoDB accède à `LastPostIndex` en utilisant la clé de partition `ForumName` afin de localiser les éléments d’index pour « EC2 ». Tous les éléments d’index avec cette clé sont stockés les uns à côté des autres pour une récupération rapide.
+ Dans ce forum, DynamoDB utilise l’index pour rechercher les clés correspondant à la condition `LastPostDateTime` spécifiée.
+ L’attribut `Replies` étant projeté dans l’index, DynamoDB peut extraire cet attribut sans utiliser de débit approvisionné supplémentaire.
+ L’attribut `Tags` n’étant pas projeté dans l’index, DynamoDB doit accéder à la table `Thread` pour l’en extraire.
+ Les résultats sont renvoyés, triés par `LastPostDateTime`. Les entrées d’index sont triées par valeur de clé de partition, puis par valeur de clé de tri, et `Query` les renvoie dans l’ordre de leur stockage (vous pouvez utiliser le paramètre `ScanIndexForward` pour renvoyer les résultats dans l’ordre décroissant).
L’attribut `Tags` n’étant pas projeté dans l’index secondaire local, DynamoDB doit utiliser des unités de capacité de lecture supplémentaires pour l’extraire de la table de base. Si vous devez exécuter cette requête souvent, nous vous recommandons de projeter `Tags` dans `LastPostIndex` pour éviter une extraction à partir de la table de base. Toutefois, si vous n’avez besoin d’accéder à `Tags` qu’occasionnellement, il se peut que le coût de stockage supplémentaire lié à la projection de `Tags` dans l’index n’en vaille pas la peine.
### Analyse d’un index secondaire local
Vous pouvez utiliser l’opération `Scan` pour extraire toutes les données d’un index secondaire local. Vous devez fournir le nom de la table de base et le nom de l’index dans la demande. Avec une opération `Scan`, DynamoDB lit toutes les données de l’index et les renvoie à l’application. Vous pouvez également demander que seules quelques données soient retournées, et que les données restantes soient ignorées. Pour ce faire, utilisez le paramètre `FilterExpression` de l’API `Scan`. Pour de plus amples informations, veuillez consulter [Filtrer les expressions à des fins d’analyse](Scan.md#Scan.FilterExpression).
## Écritures d’élément et index secondaires locaux
DynamoDB conserve automatiquement tous les index secondaires locaux synchronisés avec leurs tables de base respectives. Les applications n’écrivent jamais directement sur un index. Cependant, il est important de comprendre les implications de la façon dont DynamoDB gère ces index.
Lorsque vous créez un index secondaire local, vous spécifiez un attribut qui servira de clé de tri pour l’index. Vous spécifiez également un type de données pour cet attribut. Cela signifie que, chaque fois que vous écrivez un élément dans la table de base, si l’élément définit un attribut de clé d’index, son type doit correspondre au type de données du schéma de clé d’index. Dans le cas de `LastPostIndex`, la clé de tri `LastPostDateTime` dans l’index est définie comme un type de données `String`. Si vous essayez d’ajouter un élément à la table `Thread` et spécifiez un type de données différent pour `LastPostDateTime` (par exemple, `Number`), DynamoDB renvoie une `ValidationException` en raison de la discordance des types de données.
Il n'est pas nécessaire d' one-to-oneétablir une relation entre les éléments d'une table de base et ceux d'un index secondaire local. En fait, ce comportement peut être avantageux pour de nombreuses applications.
Une table avec de nombreux index secondaires locaux s’expose à des coûts plus élevés pour l’activité d’écriture qu’une table ayant moins d’index. Pour de plus amples informations, veuillez consulter [Considérations relatives au débit alloué pour les index secondaires locaux](#LSI.ThroughputConsiderations).
**Important**
Pour les tables avec des index secondaires locaux, il existe une limite de taille de 10 Go par valeur de clé de partition. Une table avec des index secondaires locaux peut stocker n’importe quel nombre d’éléments, à condition qu’aucune valeur de clé de partition n’ait une taille supérieure à 10 Go. Pour de plus amples informations, veuillez consulter [Taille limite de collection d’éléments](#LSI.ItemCollections.SizeLimit).
## Considérations relatives au débit alloué pour les index secondaires locaux
Lorsque vous créez une table dans DynamoDB, vous approvisionnez des unités de capacité de lecture et d’écriture pour la charge de travail prévue de la table. Cette charge de travail inclut l’activité de lecture et d’écriture sur les index secondaires locaux de la table.
Pour voir les prix actuels de capacité de débit approvisionnée, consultez [Tarification Amazon DynamoDB](https://aws.amazon.com/dynamodb/pricing).
### Unités de capacité de lecture
Lorsque vous interrogez un index secondaire local, le nombre d’unités de capacité de lecture consommées dépend du mode d’accès aux données.
Comme une interrogation de table, une interrogation d’index peut utiliser des lectures éventuellement ou fortement cohérentes en fonction de la valeur de `ConsistentRead`. Une lecture fortement cohérente utilise une unité de capacité de lecture ; une lecture éventuellement cohérente n’en utilise que la moitié. Ainsi, en choisissant des lectures éventuellement cohérentes, vous pouvez réduire vos coûts d’unités de capacité de lecture.
Pour les interrogations d’index qui demandent uniquement des clés d’index et des attributs projetés, DynamoDB calcule l’activité de lecture approvisionnée de la même façon que pour des requêtes sur des tables. La seule différence est que le calcul est basé sur les tailles des entrées d’index, plutôt que sur la taille de l’élément de la table de base. Le nombre d’unités de capacité de lecture est la somme des tailles de tous les attributs projetés de tous les éléments renvoyés. Le résultat est ensuite arrondi à la limite de 4 Ko suivante. Pour plus d’informations sur la façon dont DynamoDB calcule l’utilisation du débit approvisionné, consultez [Mode de capacité provisionnée DynamoDB](provisioned-capacity-mode.md).
Pour les interrogations d’index qui lisent des attributs qui ne sont pas projetés dans l’index secondaire local, DynamoDB doit extraire ces attributs de la table de base, en plus de lire les attributs projetés à partir de l’index. Ces extractions se produisent lorsque vous incluez des attributs non projetés dans les paramètres `Select` ou `ProjectionExpression` de l’opération `Query`. L’extraction entraîne une latence supplémentaire des réponses aux requêtes, ainsi qu’un surcoût de débit approvisionné. En plus des lectures de l’index secondaire local décrites précédemment, vous êtes facturé pour les unités de capacité de lecture utilisées pour extraire chaque élément de la table de base. Ces frais ont trait à la lecture de chaque élément entier de la table, pas seulement des attributs demandés.
La taille maximum des résultats renvoyés par une opération `Query` est de 1 Mo. Cela inclut les tailles de tous les noms et valeurs d’attribut à travers l’ensemble des éléments retournés. Toutefois, si une requête sur un index secondaire local amène DynamoDB à extraire des attributs d’élément de la table de base, la taille maximum des données dans les résultats peut être inférieure. Dans ce cas, la taille du résultat est la somme de :
+ La taille des éléments correspondants dans l’index, arrondie à la limite de 4 Ko suivante.
+ La taille de chaque élément correspondant dans la table de base, chaque élément étant arrondi individuellement à la limite de 4 Ko suivante.
Avec cette formule, la taille maximum des résultats renvoyés par une opération Query est toujours de 1 Mo.
Par exemple, considérons une table où la taille de chaque élément est de 300 octets. Il existe un index secondaire local sur cette table, mais seuls 200 octets de chaque élément sont projetés dans l’index. Supposons à présent que vous effectuez une opération `Query` sur cet index, que la requête nécessite une extraction de table pour chaque élément, et que la requête renvoie 4 éléments. DynamoDB additionne les valeurs suivantes :
+ La taille des éléments correspondants dans l’index : 200 octets × 4 éléments = 800 octets, valeur ensuite arrondie à 4 Ko.
+ La taille de chaque élément correspondant dans la table de base : (300 octets, arrondis à 4 Ko) × 4 éléments = 16 Ko.
La taille totale des données dans le résultat est donc de 20 Ko.
### Unités de capacité d’écriture
Quand un élément d’une table est ajouté, mis à jour ou supprimé, la mise à jour des index secondaires locaux utilise des unités de capacité d’écriture approvisionnée pour la table. Le coût total du débit alloué pour une écriture est la somme des unités de capacité d’écriture consommées par l’écriture dans la table de base, et de celles consommées par la mise à jour des index secondaires locaux.
Le coût d’écriture d’un élément dans un index secondaire local dépend de plusieurs facteurs :
+ Si vous écrivez un nouvel élément sur la table qui définit un attribut indexé, ou que vous mettez à jour un élément existant pour définir un attribut indexé précédemment non défini, une opération d’écriture est nécessaire pour insérer l’élément dans l’index.
+ Si une mise à jour de la table change la valeur d’un attribut de clé indexé (de A en B), deux écritures sont requises, une pour supprimer l’élément précédent de l’index et une autre pour insérer le nouvel élément dans l’index.
+ Si un élément était présent dans l’index, mais qu’une écriture sur la table a entraîné la suppression de l’attribut indexé, une écriture est nécessaire pour supprimer de l’index la projection de l’ancien élément.
+ Si un élément n’est pas présent dans l’index avant ou après la mise à jour de l’élément, il n’y a aucun coût d’écriture supplémentaire pour l’index.
Tous ces facteurs partent du principe que la taille de chaque élément dans l’index est inférieure ou égale à la taille d’élément de 1 Ko pour le calcul des unités de capacité d’écriture. Les plus grandes entrées d’index nécessitent des unités de capacité en écriture supplémentaires. Vous pouvez réduire vos coûts d’écriture en considérant les attributs que vos requêtes ont besoin de renvoyer et en projetant uniquement ces attributs dans l’index.
## Considérations relatives au stockage pour les index secondaires locaux
Quand une application écrit un élément dans une table, DynamoDB copie automatiquement le sous-ensemble approprié d’attributs vers les index secondaires locaux où ces attributs doivent apparaître. Votre AWS compte est débité pour le stockage de l'article dans la table de base ainsi que pour le stockage des attributs dans les index secondaires locaux de cette table.
La quantité d’espace utilisée par un élément de l’index est la somme des éléments suivants :
+ La taille en octets de la clé primaire de la table de base (clé de partition et clé de tri)
+ La taille en octets de l’attribut de clé d’index
+ La taille en octets des attributs projetés (le cas échéant)
+ 100 octets de surcharge par élément d’index
Pour estimer les besoins en stockage d’un index secondaire local, vous pouvez estimer la taille moyenne d’un élément de l’index, puis multiplier cette valeur par le nombre d’éléments présents dans l’index.
Si une table contient un élément dans lequel un attribut particulier n’est pas défini, tandis que cet attribut est défini en tant que clé de tri d’index, DynamoDB n’écrit aucune donnée pour cet élément dans l’index.
## Collections d’articles dans les index secondaires locaux
**Note**
Cette section concerne uniquement les tables qui ont des index secondaires locaux.
Dans DynamoDB, une *collection d’éléments* est un groupe quelconque d’éléments ayant la même valeur de clé de partition dans une table, ainsi que de tous leurs index secondaires locaux. Dans les exemples utilisés tout au long de cette section, la clé de partition pour la table `Thread` est `ForumName`, et la clé de partition pour `LastPostIndex` est également `ForumName`. Tous les éléments de table et d’index ayant le même `ForumName` font partie de la même collection d’éléments. Par exemple, la table `Thread` et l’index secondaire local `LastPostIndex` contiennent une collection d’éléments pour le forum `EC2`, et une autre pour le forum `RDS`.
Le diagramme suivant illustre la collection d’éléments pour le forum `S3`.
![\[Collection d’éléments DynamoDB comportant des éléments d’index secondaire global ayant la même valeur de clé de partition S3.\]](http://docs.aws.amazon.com/fr_fr/amazondynamodb/latest/developerguide/images/LSI_04.png)
Dans ce diagramme, la collection d’éléments se compose de tous les éléments figurant dans `Thread` et `LastPostIndex`, où la valeur de clé de partition `ForumName` est « S3 ». S’il y avait d’autres index secondaires locaux sur la table, tous les éléments dans ces index dont la valeur de `ForumName` est « S3 » feraient également partie de la collection d’éléments.
Vous pouvez utiliser n’importe laquelle des opérations suivantes dans DynamoDB pour renvoyer des informations sur les collections d’éléments :
+ `BatchWriteItem`
+ `DeleteItem`
+ `PutItem`
+ `UpdateItem`
+ `TransactWriteItems`
Chacune de ces opérations prend en charge le paramètre `ReturnItemCollectionMetrics`. Lorsque vous définissez ce paramètre sur `SIZE`, vous pouvez afficher des informations sur la taille de chaque collection d’éléments dans l’index.
**Example**
Voici un exemple de sortie d’une opération `UpdateItem` sur la table `Thread`, avec la valeur `ReturnItemCollectionMetrics` définie sur `SIZE`. L’élément mis à jour avait une valeur `ForumName` de « EC2 », de sorte que la sortie inclut des informations sur cette collection d’éléments.
```
{
ItemCollectionMetrics: {
ItemCollectionKey: {
ForumName: "EC2"
},
SizeEstimateRangeGB: [0.0, 1.0]
}
}
```
L’objet `SizeEstimateRangeGB` montre que la taille de cette collection d’éléments est comprise entre 0 et 1 Go. DynamoDB mettant régulièrement à jour cette estimation de taille, les nombres pourraient être différents lors de la prochaine modification de l’élément.
### Taille limite de collection d’éléments
La taille maximale de toute collection d’éléments pour une table possédant un ou plusieurs index secondaires locaux est de 10 Go. Cela ne s’applique pas aux collections d’éléments des tables sans index secondaires locaux, ni aux collections d’éléments dans des index secondaires globaux. Seules les tables ayant un ou plusieurs index secondaires locaux sont concernées.
Si une collection d'articles dépasse la limite de 10 Go, DynamoDB peut renvoyer `ItemCollectionSizeLimitExceededException` un, et vous ne pourrez peut-être pas ajouter d'autres articles à la collection d'articles ou augmenter la taille des éléments qui se trouvent dans la collection d'articles. (les opérations de lecture et d’écriture qui réduisent la taille de la collection d’éléments restent autorisées). Vous pouvez toujours ajouter des éléments à d’autres collections d’éléments.
Pour réduire la taille d’une collection d’éléments, vous pouvez effectuer l’une des opérations suivantes :
+ Supprimer tous les éléments inutiles avec la valeur de clé de partition en question. Lorsque vous supprimez ces éléments de la table de base, DynamoDB supprime également toutes les entrées d’index ayant la même valeur de clé de partition.
+ Mettre à jour les éléments en supprimant des attributs ou en réduisant la taille des attributs. Si ces attributs sont projetés dans des index secondaires locaux, DynamoDB réduit également la taille des entrées d’index correspondantes.
+ Créer une table avec les mêmes clés de partition et de tri, puis déplacer les éléments de l’ancienne table vers la nouvelle. Cela peut être une bonne approche si une table contient des données historiques rarement utilisées. Vous pouvez également envisager d’archiver ces données historiques sur Amazon Simple Storage Service (Amazon S3).
Lorsque la taille totale de la collection d’éléments passe sous le seuil de 10 Go, vous pouvez à nouveau ajouter des éléments avec la même valeur de clé de partition.
En guise de bonne pratique, nous vous recommandons d’instrumenter votre application pour contrôler les tailles de vos collections d’éléments. Une façon de le faire consiste à définir le paramètre `ReturnItemCollectionMetrics` sur `SIZE` chaque fois que vous utilisez `BatchWriteItem`, `DeleteItem`, `PutItem` ou `UpdateItem`. Votre application doit examiner l’objet `ReturnItemCollectionMetrics` dans la sortie et journaliser un message d’erreur chaque fois qu’une collection d’éléments dépasse une limite de taille définie par l’utilisateur (par exemple, 8 Go). Définir une limite inférieure à 10 Go fournirait un système d’avertissement précoce qui vous permettrait de savoir qu’une collection d’éléments approche de la limite dans le temps pour faire quelque chose à ce sujet.
### Collections et partitions d’éléments
Dans une table avec un ou plusieurs index secondaires locaux, chaque collection d’éléments est stockée dans une partition. La taille totale d’une collection d’éléments de ce type est limitée à la capacité de cette partition, soit 10 Go. Pour une application dans laquelle le modèle de données inclut des collections d’éléments de taille illimitée, ou dans laquelle vous pouvez raisonnablement vous attendre à ce que certaines collections d’éléments dépassent 10 Go à l’avenir, envisagez plutôt d’utiliser un index secondaire global.
Vous devez concevoir vos applications de sorte que les données de table soient réparties uniformément entre des valeurs de clé de partition distinctes. Pour les tables avec des index secondaires locaux, vos applications ne doivent pas créer de « points chauds » d’activité de lecture et d’écriture au sein d’une seule collection d’éléments sur une seule partition.
# Utilisation d'index secondaires locaux : Java
Vous pouvez utiliser l'API AWS SDK pour Java Document pour créer une table Amazon DynamoDB avec un ou plusieurs index secondaires locaux, décrire les index de la table et effectuer des requêtes à l'aide des index.
Les étapes les plus courantes pour les opérations sur les tables à l'aide de l'API AWS SDK pour Java Document sont les suivantes.
1. Créez une instance de la classe `DynamoDB`.
1. Fournissez les paramètres obligatoires et facultatifs pour l'opération en créant les objets de requête correspondants.
1. Appelez la méthode appropriée fournie par le client, que vous avez créée à l'étape précédente.
**Topics**
+ [Créer une table avec un index secondaire local](#LSIJavaDocumentAPI.CreateTableWithIndex)
+ [Décrire une table avec un index secondaire local](#LSIJavaDocumentAPI.DescribeTableWithIndex)
+ [Interroger un index secondaire local](#LSIJavaDocumentAPI.QueryAnIndex)
+ [Exemple : index secondaires locaux utilisant l'API de document de Java](LSIJavaDocumentAPI.Example.md)
## Créer une table avec un index secondaire local
Vous devez créer des index secondaires locaux au moment où vous créez une table. Pour ce faire, utilisez la méthode `createTable` et fournissez vos spécifications pour un ou plusieurs index secondaires locaux. L'exemple de code Java suivant crée une table destinée à accueillir des informations sur des chansons dans une collection musicale. La clé de partition est `Artist`, et la clé de tri `SongTitle`. Un index secondaire, `AlbumTitleIndex`, facilite les requêtes par titre d'album.
Voici les étapes à suivre pour créer une table avec un index secondaire local à l'aide de l'API Document DynamoDB.
1. Créez une instance de la classe `DynamoDB`.
1. Créez une instance de la classe `CreateTableRequest` pour fournir l'information de requête.
Vous devez fournir le nom de la table, sa clé primaire et les valeurs de débit approvisionné. Pour l'index secondaire local, vous devez fournir le nom d'index, le nom et le type de données pour la clé de tri d'index, le schéma de clé pour l'index et la projection d'attribut.
1. Appelez la méthode `createTable` en fournissant l'objet de demande comme paramètre.
L’exemple de code Java suivant illustre les tâches précédentes. Le code crée une table (`Music`) avec un index secondaire sur l'attribut `AlbumTitle`. Les clés de partition et de tri de table, ainsi que la clé de tri d'index, sont les seuls attributs projetés dans l'index.
```
AmazonDynamoDB client = AmazonDynamoDBClientBuilder.standard().build();
DynamoDB dynamoDB = new DynamoDB(client);
String tableName = "Music";
CreateTableRequest createTableRequest = new CreateTableRequest().withTableName(tableName);
//ProvisionedThroughput
createTableRequest.setProvisionedThroughput(new ProvisionedThroughput().withReadCapacityUnits((long)5).withWriteCapacityUnits((long)5));
//AttributeDefinitions
ArrayList attributeDefinitions= new ArrayList();
attributeDefinitions.add(new AttributeDefinition().withAttributeName("Artist").withAttributeType("S"));
attributeDefinitions.add(new AttributeDefinition().withAttributeName("SongTitle").withAttributeType("S"));
attributeDefinitions.add(new AttributeDefinition().withAttributeName("AlbumTitle").withAttributeType("S"));
createTableRequest.setAttributeDefinitions(attributeDefinitions);
//KeySchema
ArrayList tableKeySchema = new ArrayList();
tableKeySchema.add(new KeySchemaElement().withAttributeName("Artist").withKeyType(KeyType.HASH)); //Partition key
tableKeySchema.add(new KeySchemaElement().withAttributeName("SongTitle").withKeyType(KeyType.RANGE)); //Sort key
createTableRequest.setKeySchema(tableKeySchema);
ArrayList indexKeySchema = new ArrayList();
indexKeySchema.add(new KeySchemaElement().withAttributeName("Artist").withKeyType(KeyType.HASH)); //Partition key
indexKeySchema.add(new KeySchemaElement().withAttributeName("AlbumTitle").withKeyType(KeyType.RANGE)); //Sort key
Projection projection = new Projection().withProjectionType(ProjectionType.INCLUDE);
ArrayList nonKeyAttributes = new ArrayList();
nonKeyAttributes.add("Genre");
nonKeyAttributes.add("Year");
projection.setNonKeyAttributes(nonKeyAttributes);
LocalSecondaryIndex localSecondaryIndex = new LocalSecondaryIndex()
.withIndexName("AlbumTitleIndex").withKeySchema(indexKeySchema).withProjection(projection);
ArrayList localSecondaryIndexes = new ArrayList();
localSecondaryIndexes.add(localSecondaryIndex);
createTableRequest.setLocalSecondaryIndexes(localSecondaryIndexes);
Table table = dynamoDB.createTable(createTableRequest);
System.out.println(table.getDescription());
```
Vous devez attendre que DynamoDB crée la table et définisse l'état de celle-ci sur `ACTIVE`. Après cela, vous pouvez commencer à insérer des éléments de données dans la table.
## Décrire une table avec un index secondaire local
Pour obtenir des informations concernant les index secondaires locaux sur une table, utilisez la méthode `describeTable`. Pour chaque index, vous pouvez accéder à son nom, à son schéma de clé et aux attributs projetés.
Voici les étapes à suivre pour accéder aux informations d'index secondaire local sur une table à l'aide de l'API Document AWS SDK pour Java .
1. Créez une instance de la classe `DynamoDB`.
1. Créez une instance de la classe `Table`. Vous devez fournir le nom de la table.
1. Appelez la méthode `describeTable` sur l'objet `Table`.
L’exemple de code Java suivant illustre les tâches précédentes.
**Example**
```
AmazonDynamoDB client = AmazonDynamoDBClientBuilder.standard().build();
DynamoDB dynamoDB = new DynamoDB(client);
String tableName = "Music";
Table table = dynamoDB.getTable(tableName);
TableDescription tableDescription = table.describe();
List localSecondaryIndexes
= tableDescription.getLocalSecondaryIndexes();
// This code snippet will work for multiple indexes, even though
// there is only one index in this example.
Iterator lsiIter = localSecondaryIndexes.iterator();
while (lsiIter.hasNext()) {
LocalSecondaryIndexDescription lsiDescription = lsiIter.next();
System.out.println("Info for index " + lsiDescription.getIndexName() + ":");
Iterator kseIter = lsiDescription.getKeySchema().iterator();
while (kseIter.hasNext()) {
KeySchemaElement kse = kseIter.next();
System.out.printf("\t%s: %s\n", kse.getAttributeName(), kse.getKeyType());
}
Projection projection = lsiDescription.getProjection();
System.out.println("\tThe projection type is: " + projection.getProjectionType());
if (projection.getProjectionType().toString().equals("INCLUDE")) {
System.out.println("\t\tThe non-key projected attributes are: " + projection.getNonKeyAttributes());
}
}
```
## Interroger un index secondaire local
Vous pouvez utiliser l'opération `Query` sur un index secondaire local de la même manière que vous utilisez l'opération `Query` sur une table. Vous devez spécifier le nom d’index, les critères de requête pour la clé de tri d’index et les attributs que vous souhaitez renvoyer. Dans cet exemple, l’index est `AlbumTitleIndex` et la clé de tri d’index est `AlbumTitle`.
Les seuls attributs renvoyés sont ceux qui ont été projetés dans l’index. Vous pourriez également modifier cette requête pour sélectionner des attributs autres que de clé, mais cela nécessiterait une activité d’extraction de table relativement coûteuse. Pour plus d’informations sur les extractions de table, consultez [Projections d’attribut](LSI.md#LSI.Projections).
Voici les étapes à suivre pour interroger un index secondaire local à l'aide de l'API AWS SDK pour Java Document.
1. Créez une instance de la classe `DynamoDB`.
1. Créez une instance de la classe `Table`. Vous devez fournir le nom de la table.
1. Créez une instance de la classe `Index`. Vous devez fournir le nom d'index.
1. Appelez la méthode `query` de la classe `Index`.
L’exemple de code Java suivant illustre les tâches précédentes.
**Example**
```
AmazonDynamoDB client = AmazonDynamoDBClientBuilder.standard().build();
DynamoDB dynamoDB = new DynamoDB(client);
String tableName = "Music";
Table table = dynamoDB.getTable(tableName);
Index index = table.getIndex("AlbumTitleIndex");
QuerySpec spec = new QuerySpec()
.withKeyConditionExpression("Artist = :v_artist and AlbumTitle = :v_title")
.withValueMap(new ValueMap()
.withString(":v_artist", "Acme Band")
.withString(":v_title", "Songs About Life"));
ItemCollection items = index.query(spec);
Iterator
- itemsIter = items.iterator();
while (itemsIter.hasNext()) {
Item item = itemsIter.next();
System.out.println(item.toJSONPretty());
}
```
### Lectures cohérentes sur un index secondaire local
Contrairement aux index secondaires globaux, qui ne prennent en charge que les lectures finalement cohérentes, un index secondaire local prend en charge à la fois les lectures cohérentes et les lectures fortement cohérentes. Une lecture fortement cohérente d’un index secondaire local renvoie toujours les dernières valeurs mises à jour. Si la requête doit extraire des attributs supplémentaires de la table de base, ces attributs extraits sont également cohérents par rapport à l'index.
Par défaut, `Query` utilise éventuellement des lectures cohérentes. Pour demander une lecture très cohérente, réglez `ConsistentRead` sur `true` dans le`QuerySpec`. Les exemples de requêtes suivants `AlbumTitleIndex` utilisant une lecture très cohérente :
**Example**
```
QuerySpec spec = new QuerySpec()
.withKeyConditionExpression("Artist = :v_artist and AlbumTitle = :v_title")
.withValueMap(new ValueMap()
.withString(":v_artist", "Acme Band")
.withString(":v_title", "Songs About Life"))
.withConsistentRead(true);
```
**Note**
Une lecture très cohérente consomme une unité de capacité de lecture pour 4 Ko de données renvoyées (arrondies au chiffre supérieur), alors qu'une lecture finalement cohérente en consomme la moitié. Par exemple, une lecture hautement cohérente qui renvoie 9 Ko de données consomme 3 unités de capacité de lecture (9 Ko/4 Ko = 2,25, arrondi à 3), tandis que la même requête utilisant une lecture finalement cohérente consomme 1,5 unité de capacité de lecture. Si votre application peut tolérer la lecture de données légèrement périmées, utilisez éventuellement des lectures cohérentes afin de réduire l'utilisation de votre capacité de lecture. Pour de plus amples informations, veuillez consulter [Unités de capacité de lecture](LSI.md#LSI.ThroughputConsiderations.Reads).
# Exemple : index secondaires locaux utilisant l'API de document de Java
L'exemple de code Java suivant montre comment utiliser les index secondaires locaux dans Amazon DynamoDB. L'exemple crée une table nommée `CustomerOrders` avec une clé de partition `CustomerId` et une clé de tri `OrderId`. Il y a deux index secondaires locaux sur cette table :
+ `OrderCreationDateIndex` – La clé de tri est.`OrderCreationDate`, et les attributs suivants sont projetés dans l'index :
+ `ProductCategory`
+ `ProductName`
+ `OrderStatus`
+ `ShipmentTrackingId`
+ `IsOpenIndex` – La clé de tri est `IsOpen` et tous les attributs de table sont projetés dans l'index.
Une fois la table `CustomerOrders` créée, le programme charge la table avec des données représentant des commandes de clients. Il interroge ensuite les données à l'aide d'index secondaires locaux. Enfin, le programme supprime la table `CustomerOrders`.
Pour step-by-step obtenir des instructions sur le test de l'échantillon suivant, reportez-vous à[Exemples de code Java](CodeSamples.Java.md).
**Example**
```
package com.example.dynamodb;
import software.amazon.awssdk.core.waiters.WaiterResponse;
import software.amazon.awssdk.services.dynamodb.DynamoDbClient;
import software.amazon.awssdk.services.dynamodb.model.*;
import software.amazon.awssdk.services.dynamodb.waiters.DynamoDbWaiter;
import java.util.HashMap;
import java.util.Map;
public class DocumentAPILocalSecondaryIndexExample {
static DynamoDbClient client = DynamoDbClient.create();
public static String tableName = "CustomerOrders";
public static void main(String[] args) {
createTable();
loadData();
query(null);
query("IsOpenIndex");
query("OrderCreationDateIndex");
deleteTable(tableName);
}
public static void createTable() {
CreateTableRequest request = CreateTableRequest.builder()
.tableName(tableName)
.provisionedThroughput(ProvisionedThroughput.builder()
.readCapacityUnits(1L)
.writeCapacityUnits(1L)
.build())
.attributeDefinitions(
AttributeDefinition.builder().attributeName("CustomerId").attributeType(ScalarAttributeType.S).build(),
AttributeDefinition.builder().attributeName("OrderId").attributeType(ScalarAttributeType.N).build(),
AttributeDefinition.builder().attributeName("OrderCreationDate").attributeType(ScalarAttributeType.N).build(),
AttributeDefinition.builder().attributeName("IsOpen").attributeType(ScalarAttributeType.N).build())
.keySchema(
KeySchemaElement.builder().attributeName("CustomerId").keyType(KeyType.HASH).build(),
KeySchemaElement.builder().attributeName("OrderId").keyType(KeyType.RANGE).build())
.localSecondaryIndexes(
LocalSecondaryIndex.builder()
.indexName("OrderCreationDateIndex")
.keySchema(
KeySchemaElement.builder().attributeName("CustomerId").keyType(KeyType.HASH).build(),
KeySchemaElement.builder().attributeName("OrderCreationDate").keyType(KeyType.RANGE).build())
.projection(Projection.builder()
.projectionType(ProjectionType.INCLUDE)
.nonKeyAttributes("ProductCategory", "ProductName")
.build())
.build(),
LocalSecondaryIndex.builder()
.indexName("IsOpenIndex")
.keySchema(
KeySchemaElement.builder().attributeName("CustomerId").keyType(KeyType.HASH).build(),
KeySchemaElement.builder().attributeName("IsOpen").keyType(KeyType.RANGE).build())
.projection(Projection.builder()
.projectionType(ProjectionType.ALL)
.build())
.build())
.build();
System.out.println("Creating table " + tableName + "...");
client.createTable(request);
try (DynamoDbWaiter waiter = client.waiter()) {
WaiterResponse response = waiter.waitUntilTableExists(r -> r.tableName(tableName));
response.matched().response().ifPresent(System.out::println);
}
}
public static void query(String indexName) {
System.out.println("\n***********************************************************\n");
System.out.println("Querying table " + tableName + "...");
if ("IsOpenIndex".equals(indexName)) {
System.out.println("\nUsing index: '" + indexName + "': Bob's orders that are open.");
System.out.println("Only a user-specified list of attributes are returned\n");
Map values = new HashMap<>();
values.put(":v_custid", AttributeValue.builder().s("bob@example.com").build());
values.put(":v_isopen", AttributeValue.builder().n("1").build());
QueryRequest request = QueryRequest.builder()
.tableName(tableName)
.indexName(indexName)
.keyConditionExpression("CustomerId = :v_custid and IsOpen = :v_isopen")
.expressionAttributeValues(values)
.projectionExpression("OrderCreationDate, ProductCategory, ProductName, OrderStatus")
.build();
System.out.println("Query: printing results...");
client.query(request).items().forEach(System.out::println);
} else if ("OrderCreationDateIndex".equals(indexName)) {
System.out.println("\nUsing index: '" + indexName + "': Bob's orders that were placed after 01/31/2015.");
System.out.println("Only the projected attributes are returned\n");
Map values = new HashMap<>();
values.put(":v_custid", AttributeValue.builder().s("bob@example.com").build());
values.put(":v_orddate", AttributeValue.builder().n("20150131").build());
QueryRequest request = QueryRequest.builder()
.tableName(tableName)
.indexName(indexName)
.keyConditionExpression("CustomerId = :v_custid and OrderCreationDate >= :v_orddate")
.expressionAttributeValues(values)
.select(Select.ALL_PROJECTED_ATTRIBUTES)
.build();
System.out.println("Query: printing results...");
client.query(request).items().forEach(System.out::println);
} else {
System.out.println("\nNo index: All of Bob's orders, by OrderId:\n");
Map values = new HashMap<>();
values.put(":v_custid", AttributeValue.builder().s("bob@example.com").build());
QueryRequest request = QueryRequest.builder()
.tableName(tableName)
.keyConditionExpression("CustomerId = :v_custid")
.expressionAttributeValues(values)
.build();
System.out.println("Query: printing results...");
client.query(request).items().forEach(System.out::println);
}
}
public static void deleteTable(String tableName) {
System.out.println("Deleting table " + tableName + "...");
client.deleteTable(DeleteTableRequest.builder().tableName(tableName).build());
try (DynamoDbWaiter waiter = client.waiter()) {
waiter.waitUntilTableNotExists(r -> r.tableName(tableName));
}
}
public static void loadData() {
System.out.println("Loading data into table " + tableName + "...");
putItem(Map.of(
"CustomerId", AttributeValue.builder().s("alice@example.com").build(),
"OrderId", AttributeValue.builder().n("1").build(),
"IsOpen", AttributeValue.builder().n("1").build(),
"OrderCreationDate", AttributeValue.builder().n("20150101").build(),
"ProductCategory", AttributeValue.builder().s("Book").build(),
"ProductName", AttributeValue.builder().s("The Great Outdoors").build(),
"OrderStatus", AttributeValue.builder().s("PACKING ITEMS").build()));
putItem(Map.of(
"CustomerId", AttributeValue.builder().s("alice@example.com").build(),
"OrderId", AttributeValue.builder().n("2").build(),
"IsOpen", AttributeValue.builder().n("1").build(),
"OrderCreationDate", AttributeValue.builder().n("20150221").build(),
"ProductCategory", AttributeValue.builder().s("Bike").build(),
"ProductName", AttributeValue.builder().s("Super Mountain").build(),
"OrderStatus", AttributeValue.builder().s("ORDER RECEIVED").build()));
putItem(Map.of(
"CustomerId", AttributeValue.builder().s("alice@example.com").build(),
"OrderId", AttributeValue.builder().n("3").build(),
"OrderCreationDate", AttributeValue.builder().n("20150304").build(),
"ProductCategory", AttributeValue.builder().s("Music").build(),
"ProductName", AttributeValue.builder().s("A Quiet Interlude").build(),
"OrderStatus", AttributeValue.builder().s("IN TRANSIT").build(),
"ShipmentTrackingId", AttributeValue.builder().s("176493").build()));
putItem(Map.of(
"CustomerId", AttributeValue.builder().s("bob@example.com").build(),
"OrderId", AttributeValue.builder().n("1").build(),
"OrderCreationDate", AttributeValue.builder().n("20150111").build(),
"ProductCategory", AttributeValue.builder().s("Movie").build(),
"ProductName", AttributeValue.builder().s("Calm Before The Storm").build(),
"OrderStatus", AttributeValue.builder().s("SHIPPING DELAY").build(),
"ShipmentTrackingId", AttributeValue.builder().s("859323").build()));
putItem(Map.of(
"CustomerId", AttributeValue.builder().s("bob@example.com").build(),
"OrderId", AttributeValue.builder().n("2").build(),
"OrderCreationDate", AttributeValue.builder().n("20150124").build(),
"ProductCategory", AttributeValue.builder().s("Music").build(),
"ProductName", AttributeValue.builder().s("E-Z Listening").build(),
"OrderStatus", AttributeValue.builder().s("DELIVERED").build(),
"ShipmentTrackingId", AttributeValue.builder().s("756943").build()));
putItem(Map.of(
"CustomerId", AttributeValue.builder().s("bob@example.com").build(),
"OrderId", AttributeValue.builder().n("3").build(),
"OrderCreationDate", AttributeValue.builder().n("20150221").build(),
"ProductCategory", AttributeValue.builder().s("Music").build(),
"ProductName", AttributeValue.builder().s("Symphony 9").build(),
"OrderStatus", AttributeValue.builder().s("DELIVERED").build(),
"ShipmentTrackingId", AttributeValue.builder().s("645193").build()));
putItem(Map.of(
"CustomerId", AttributeValue.builder().s("bob@example.com").build(),
"OrderId", AttributeValue.builder().n("4").build(),
"IsOpen", AttributeValue.builder().n("1").build(),
"OrderCreationDate", AttributeValue.builder().n("20150222").build(),
"ProductCategory", AttributeValue.builder().s("Hardware").build(),
"ProductName", AttributeValue.builder().s("Extra Heavy Hammer").build(),
"OrderStatus", AttributeValue.builder().s("PACKING ITEMS").build()));
putItem(Map.of(
"CustomerId", AttributeValue.builder().s("bob@example.com").build(),
"OrderId", AttributeValue.builder().n("5").build(),
"OrderCreationDate", AttributeValue.builder().n("20150309").build(),
"ProductCategory", AttributeValue.builder().s("Book").build(),
"ProductName", AttributeValue.builder().s("How To Cook").build(),
"OrderStatus", AttributeValue.builder().s("IN TRANSIT").build(),
"ShipmentTrackingId", AttributeValue.builder().s("440185").build()));
putItem(Map.of(
"CustomerId", AttributeValue.builder().s("bob@example.com").build(),
"OrderId", AttributeValue.builder().n("6").build(),
"OrderCreationDate", AttributeValue.builder().n("20150318").build(),
"ProductCategory", AttributeValue.builder().s("Luggage").build(),
"ProductName", AttributeValue.builder().s("Really Big Suitcase").build(),
"OrderStatus", AttributeValue.builder().s("DELIVERED").build(),
"ShipmentTrackingId", AttributeValue.builder().s("893927").build()));
putItem(Map.of(
"CustomerId", AttributeValue.builder().s("bob@example.com").build(),
"OrderId", AttributeValue.builder().n("7").build(),
"OrderCreationDate", AttributeValue.builder().n("20150324").build(),
"ProductCategory", AttributeValue.builder().s("Golf").build(),
"ProductName", AttributeValue.builder().s("PGA Pro II").build(),
"OrderStatus", AttributeValue.builder().s("OUT FOR DELIVERY").build(),
"ShipmentTrackingId", AttributeValue.builder().s("383283").build()));
}
private static void putItem(Map item) {
client.putItem(PutItemRequest.builder().tableName(tableName).item(item).build());
}
}
```
# Utilisation d'index secondaires locaux : .NET
**Topics**
+ [Créer une table avec un index secondaire local](#LSILowLevelDotNet.CreateTableWithIndex)
+ [Décrire une table avec un index secondaire local](#LSILowLevelDotNet.DescribeTableWithIndex)
+ [Interroger un index secondaire local](#LSILowLevelDotNet.QueryAnIndex)
+ [Exemple : index secondaires locaux utilisant l'API de AWS SDK pour .NET bas niveau](LSILowLevelDotNet.Example.md)
Vous pouvez utiliser l'API de AWS SDK pour .NET bas niveau pour créer une table Amazon DynamoDB avec un ou plusieurs index secondaires locaux, décrire les index de la table et effectuer des requêtes à l'aide des index. Ces opérations sont mappées aux actions de l'API de bas niveau DynamoDB correspondantes. Pour de plus amples informations, veuillez consulter [Exemples de code .NET](CodeSamples.DotNet.md).
Voici les étapes courantes pour les opérations de table à l'aide de l'API de bas niveau .NET.
1. Créez une instance de la classe `AmazonDynamoDBClient`.
1. Fournissez les paramètres obligatoires et facultatifs pour l'opération en créant les objets de requête correspondants.
Par exemple, créez un objet `CreateTableRequest` pour créer une table, et un objet `QueryRequest` pour interroger une table ou un index.
1. Exécutez la méthode appropriée fournie par le client, que vous avez créée à l'étape précédente.
## Créer une table avec un index secondaire local
Vous devez créer des index secondaires locaux au moment où vous créez une table. Pour ce faire, utilisez `CreateTable` et fournissez vos spécifications pour un ou plusieurs index secondaires locaux. L'exemple de code C\$1 suivant crée une table destinée à accueillir des informations sur des chansons dans une collection musicale. La clé de partition est `Artist`, et la clé de tri `SongTitle`. Un index secondaire, `AlbumTitleIndex`, facilite les requêtes par titre d'album.
Voici les étapes à suivre pour créer une table avec un index secondaire local à l'aide de l'API de bas niveau .NET.
1. Créez une instance de la classe `AmazonDynamoDBClient`.
1. Créez une instance de la classe `CreateTableRequest` pour fournir l'information de requête.
Vous devez fournir le nom de la table, sa clé primaire et les valeurs de débit approvisionné. Pour l'index secondaire local, vous devez fournir le nom d'index, le nom et le type de données de la clé de tri d'index, le schéma de clé pour l'index et la projection d'attribut.
1. Exécutez la méthode `CreateTable` en fournissant l'objet de demande comme paramètre.
L’exemple de code C\$1 suivant illustre les étapes précédentes. Le code crée une table (`Music`) avec un index secondaire sur l'attribut `AlbumTitle`. Les clés de partition et de tri de table, ainsi que la clé de tri d'index, sont les seuls attributs projetés dans l'index.
```
AmazonDynamoDBClient client = new AmazonDynamoDBClient();
string tableName = "Music";
CreateTableRequest createTableRequest = new CreateTableRequest()
{
TableName = tableName
};
//ProvisionedThroughput
createTableRequest.ProvisionedThroughput = new ProvisionedThroughput()
{
ReadCapacityUnits = (long)5,
WriteCapacityUnits = (long)5
};
//AttributeDefinitions
List attributeDefinitions = new List();
attributeDefinitions.Add(new AttributeDefinition()
{
AttributeName = "Artist",
AttributeType = "S"
});
attributeDefinitions.Add(new AttributeDefinition()
{
AttributeName = "SongTitle",
AttributeType = "S"
});
attributeDefinitions.Add(new AttributeDefinition()
{
AttributeName = "AlbumTitle",
AttributeType = "S"
});
createTableRequest.AttributeDefinitions = attributeDefinitions;
//KeySchema
List tableKeySchema = new List();
tableKeySchema.Add(new KeySchemaElement() { AttributeName = "Artist", KeyType = "HASH" }); //Partition key
tableKeySchema.Add(new KeySchemaElement() { AttributeName = "SongTitle", KeyType = "RANGE" }); //Sort key
createTableRequest.KeySchema = tableKeySchema;
List indexKeySchema = new List();
indexKeySchema.Add(new KeySchemaElement() { AttributeName = "Artist", KeyType = "HASH" }); //Partition key
indexKeySchema.Add(new KeySchemaElement() { AttributeName = "AlbumTitle", KeyType = "RANGE" }); //Sort key
Projection projection = new Projection() { ProjectionType = "INCLUDE" };
List nonKeyAttributes = new List();
nonKeyAttributes.Add("Genre");
nonKeyAttributes.Add("Year");
projection.NonKeyAttributes = nonKeyAttributes;
LocalSecondaryIndex localSecondaryIndex = new LocalSecondaryIndex()
{
IndexName = "AlbumTitleIndex",
KeySchema = indexKeySchema,
Projection = projection
};
List localSecondaryIndexes = new List();
localSecondaryIndexes.Add(localSecondaryIndex);
createTableRequest.LocalSecondaryIndexes = localSecondaryIndexes;
CreateTableResponse result = client.CreateTable(createTableRequest);
Console.WriteLine(result.CreateTableResult.TableDescription.TableName);
Console.WriteLine(result.CreateTableResult.TableDescription.TableStatus);
```
Vous devez attendre que DynamoDB crée la table et définisse l'état de celle-ci sur `ACTIVE`. Après cela, vous pouvez commencer à insérer des éléments de données dans la table.
## Décrire une table avec un index secondaire local
Pour obtenir des informations concernant les index secondaires locaux sur une table, utilisez l'API `DescribeTable`. Pour chaque index, vous pouvez accéder à son nom, à son schéma de clé et aux attributs projetés.
Voici les étapes à suivre pour accéder aux informations d'index secondaire local pour une table à l'aide de l'API de bas niveau .NET.
1. Créez une instance de la classe `AmazonDynamoDBClient`.
1. Créez une instance de la classe `DescribeTableRequest` pour fournir l'information de requête. Vous devez fournir le nom de la table.
1. Exécutez la méthode `describeTable` en fournissant l'objet de demande comme paramètre.
L’exemple de code C\$1 suivant illustre les étapes précédentes.
**Example**
```
AmazonDynamoDBClient client = new AmazonDynamoDBClient();
string tableName = "Music";
DescribeTableResponse response = client.DescribeTable(new DescribeTableRequest() { TableName = tableName });
List localSecondaryIndexes =
response.DescribeTableResult.Table.LocalSecondaryIndexes;
// This code snippet will work for multiple indexes, even though
// there is only one index in this example.
foreach (LocalSecondaryIndexDescription lsiDescription in localSecondaryIndexes)
{
Console.WriteLine("Info for index " + lsiDescription.IndexName + ":");
foreach (KeySchemaElement kse in lsiDescription.KeySchema)
{
Console.WriteLine("\t" + kse.AttributeName + ": key type is " + kse.KeyType);
}
Projection projection = lsiDescription.Projection;
Console.WriteLine("\tThe projection type is: " + projection.ProjectionType);
if (projection.ProjectionType.ToString().Equals("INCLUDE"))
{
Console.WriteLine("\t\tThe non-key projected attributes are:");
foreach (String s in projection.NonKeyAttributes)
{
Console.WriteLine("\t\t" + s);
}
}
}
```
## Interroger un index secondaire local
Vous pouvez utiliser l'opération `Query` sur un index secondaire local de la même manière que vous utilisez l'opération `Query` sur une table. Vous devez spécifier le nom d'index, les critères de requête pour la clé de tri d'index et les attributs que vous souhaitez renvoyer. Dans cet exemple, l'index est `AlbumTitleIndex` et la clé de tri d'index est `AlbumTitle`.
Les seuls attributs renvoyés sont ceux qui ont été projetés dans l'index. Vous pourriez également modifier cette requête pour sélectionner des attributs autres que de clé, mais cela nécessiterait une activité d'extraction de table relativement coûteuse. Pour plus d'informations sur les extractions de table, consultez [Projections d’attribut](LSI.md#LSI.Projections)
Voici les étapes à suivre pour interroger un index secondaire local à l'aide de l'API de bas niveau .NET.
1. Créez une instance de la classe `AmazonDynamoDBClient`.
1. Créez une instance de la classe `QueryRequest` pour fournir l'information de requête.
1. Exécutez la méthode `query` en fournissant l'objet de demande comme paramètre.
L’exemple de code C\$1 suivant illustre les étapes précédentes.
**Example**
```
QueryRequest queryRequest = new QueryRequest
{
TableName = "Music",
IndexName = "AlbumTitleIndex",
Select = "ALL_ATTRIBUTES",
ScanIndexForward = true,
KeyConditionExpression = "Artist = :v_artist and AlbumTitle = :v_title",
ExpressionAttributeValues = new Dictionary()
{
{":v_artist",new AttributeValue {S = "Acme Band"}},
{":v_title",new AttributeValue {S = "Songs About Life"}}
},
};
QueryResponse response = client.Query(queryRequest);
foreach (var attribs in response.Items)
{
foreach (var attrib in attribs)
{
Console.WriteLine(attrib.Key + " ---> " + attrib.Value.S);
}
Console.WriteLine();
}
```
# Exemple : index secondaires locaux utilisant l'API de AWS SDK pour .NET bas niveau
L'exemple de code C\$1 suivant montre comment utiliser les index secondaires locaux dans Amazon DynamoDB. L'exemple crée une table nommée `CustomerOrders` avec une clé de partition `CustomerId` et une clé de tri `OrderId`. Il y a deux index secondaires locaux sur cette table :
+ `OrderCreationDateIndex` – La clé de tri est.`OrderCreationDate`, et les attributs suivants sont projetés dans l'index :
+ `ProductCategory`
+ `ProductName`
+ `OrderStatus`
+ `ShipmentTrackingId`
+ `IsOpenIndex` – La clé de tri est `IsOpen` et tous les attributs de table sont projetés dans l'index.
Une fois la table `CustomerOrders` créée, le programme charge la table avec des données représentant des commandes de clients. Il interroge ensuite les données à l'aide d'index secondaires locaux. Enfin, le programme supprime la table `CustomerOrders`.
Pour step-by-step obtenir des instructions sur le test de l'exemple suivant, reportez-vous à[Exemples de code .NET](CodeSamples.DotNet.md).
**Example**
```
using System;
using System.Collections.Generic;
using System.Linq;
using Amazon.DynamoDBv2;
using Amazon.DynamoDBv2.DataModel;
using Amazon.DynamoDBv2.DocumentModel;
using Amazon.DynamoDBv2.Model;
using Amazon.Runtime;
using Amazon.SecurityToken;
namespace com.amazonaws.codesamples
{
class LowLevelLocalSecondaryIndexExample
{
private static AmazonDynamoDBClient client = new AmazonDynamoDBClient();
private static string tableName = "CustomerOrders";
static void Main(string[] args)
{
try
{
CreateTable();
LoadData();
Query(null);
Query("IsOpenIndex");
Query("OrderCreationDateIndex");
DeleteTable(tableName);
Console.WriteLine("To continue, press Enter");
Console.ReadLine();
}
catch (AmazonDynamoDBException e) { Console.WriteLine(e.Message); }
catch (AmazonServiceException e) { Console.WriteLine(e.Message); }
catch (Exception e) { Console.WriteLine(e.Message); }
}
private static void CreateTable()
{
var createTableRequest =
new CreateTableRequest()
{
TableName = tableName,
ProvisionedThroughput =
new ProvisionedThroughput()
{
ReadCapacityUnits = (long)1,
WriteCapacityUnits = (long)1
}
};
var attributeDefinitions = new List()
{
// Attribute definitions for table primary key
{ new AttributeDefinition() {
AttributeName = "CustomerId", AttributeType = "S"
} },
{ new AttributeDefinition() {
AttributeName = "OrderId", AttributeType = "N"
} },
// Attribute definitions for index primary key
{ new AttributeDefinition() {
AttributeName = "OrderCreationDate", AttributeType = "N"
} },
{ new AttributeDefinition() {
AttributeName = "IsOpen", AttributeType = "N"
}}
};
createTableRequest.AttributeDefinitions = attributeDefinitions;
// Key schema for table
var tableKeySchema = new List()
{
{ new KeySchemaElement() {
AttributeName = "CustomerId", KeyType = "HASH"
} }, //Partition key
{ new KeySchemaElement() {
AttributeName = "OrderId", KeyType = "RANGE"
} } //Sort key
};
createTableRequest.KeySchema = tableKeySchema;
var localSecondaryIndexes = new List();
// OrderCreationDateIndex
LocalSecondaryIndex orderCreationDateIndex = new LocalSecondaryIndex()
{
IndexName = "OrderCreationDateIndex"
};
// Key schema for OrderCreationDateIndex
var indexKeySchema = new List()
{
{ new KeySchemaElement() {
AttributeName = "CustomerId", KeyType = "HASH"
} }, //Partition key
{ new KeySchemaElement() {
AttributeName = "OrderCreationDate", KeyType = "RANGE"
} } //Sort key
};
orderCreationDateIndex.KeySchema = indexKeySchema;
// Projection (with list of projected attributes) for
// OrderCreationDateIndex
var projection = new Projection()
{
ProjectionType = "INCLUDE"
};
var nonKeyAttributes = new List()
{
"ProductCategory",
"ProductName"
};
projection.NonKeyAttributes = nonKeyAttributes;
orderCreationDateIndex.Projection = projection;
localSecondaryIndexes.Add(orderCreationDateIndex);
// IsOpenIndex
LocalSecondaryIndex isOpenIndex
= new LocalSecondaryIndex()
{
IndexName = "IsOpenIndex"
};
// Key schema for IsOpenIndex
indexKeySchema = new List()
{
{ new KeySchemaElement() {
AttributeName = "CustomerId", KeyType = "HASH"
}}, //Partition key
{ new KeySchemaElement() {
AttributeName = "IsOpen", KeyType = "RANGE"
}} //Sort key
};
// Projection (all attributes) for IsOpenIndex
projection = new Projection()
{
ProjectionType = "ALL"
};
isOpenIndex.KeySchema = indexKeySchema;
isOpenIndex.Projection = projection;
localSecondaryIndexes.Add(isOpenIndex);
// Add index definitions to CreateTable request
createTableRequest.LocalSecondaryIndexes = localSecondaryIndexes;
Console.WriteLine("Creating table " + tableName + "...");
client.CreateTable(createTableRequest);
WaitUntilTableReady(tableName);
}
public static void Query(string indexName)
{
Console.WriteLine("\n***********************************************************\n");
Console.WriteLine("Querying table " + tableName + "...");
QueryRequest queryRequest = new QueryRequest()
{
TableName = tableName,
ConsistentRead = true,
ScanIndexForward = true,
ReturnConsumedCapacity = "TOTAL"
};
String keyConditionExpression = "CustomerId = :v_customerId";
Dictionary expressionAttributeValues = new Dictionary {
{":v_customerId", new AttributeValue {
S = "bob@example.com"
}}
};
if (indexName == "IsOpenIndex")
{
Console.WriteLine("\nUsing index: '" + indexName
+ "': Bob's orders that are open.");
Console.WriteLine("Only a user-specified list of attributes are returned\n");
queryRequest.IndexName = indexName;
keyConditionExpression += " and IsOpen = :v_isOpen";
expressionAttributeValues.Add(":v_isOpen", new AttributeValue
{
N = "1"
});
// ProjectionExpression
queryRequest.ProjectionExpression = "OrderCreationDate, ProductCategory, ProductName, OrderStatus";
}
else if (indexName == "OrderCreationDateIndex")
{
Console.WriteLine("\nUsing index: '" + indexName
+ "': Bob's orders that were placed after 01/31/2013.");
Console.WriteLine("Only the projected attributes are returned\n");
queryRequest.IndexName = indexName;
keyConditionExpression += " and OrderCreationDate > :v_Date";
expressionAttributeValues.Add(":v_Date", new AttributeValue
{
N = "20130131"
});
// Select
queryRequest.Select = "ALL_PROJECTED_ATTRIBUTES";
}
else
{
Console.WriteLine("\nNo index: All of Bob's orders, by OrderId:\n");
}
queryRequest.KeyConditionExpression = keyConditionExpression;
queryRequest.ExpressionAttributeValues = expressionAttributeValues;
var result = client.Query(queryRequest);
var items = result.Items;
foreach (var currentItem in items)
{
foreach (string attr in currentItem.Keys)
{
if (attr == "OrderId" || attr == "IsOpen"
|| attr == "OrderCreationDate")
{
Console.WriteLine(attr + "---> " + currentItem[attr].N);
}
else
{
Console.WriteLine(attr + "---> " + currentItem[attr].S);
}
}
Console.WriteLine();
}
Console.WriteLine("\nConsumed capacity: " + result.ConsumedCapacity.CapacityUnits + "\n");
}
private static void DeleteTable(string tableName)
{
Console.WriteLine("Deleting table " + tableName + "...");
client.DeleteTable(new DeleteTableRequest()
{
TableName = tableName
});
WaitForTableToBeDeleted(tableName);
}
public static void LoadData()
{
Console.WriteLine("Loading data into table " + tableName + "...");
Dictionary item = new Dictionary();
item["CustomerId"] = new AttributeValue
{
S = "alice@example.com"
};
item["OrderId"] = new AttributeValue
{
N = "1"
};
item["IsOpen"] = new AttributeValue
{
N = "1"
};
item["OrderCreationDate"] = new AttributeValue
{
N = "20130101"
};
item["ProductCategory"] = new AttributeValue
{
S = "Book"
};
item["ProductName"] = new AttributeValue
{
S = "The Great Outdoors"
};
item["OrderStatus"] = new AttributeValue
{
S = "PACKING ITEMS"
};
/* no ShipmentTrackingId attribute */
PutItemRequest putItemRequest = new PutItemRequest
{
TableName = tableName,
Item = item,
ReturnItemCollectionMetrics = "SIZE"
};
client.PutItem(putItemRequest);
item = new Dictionary();
item["CustomerId"] = new AttributeValue
{
S = "alice@example.com"
};
item["OrderId"] = new AttributeValue
{
N = "2"
};
item["IsOpen"] = new AttributeValue
{
N = "1"
};
item["OrderCreationDate"] = new AttributeValue
{
N = "20130221"
};
item["ProductCategory"] = new AttributeValue
{
S = "Bike"
};
item["ProductName"] = new AttributeValue
{
S = "Super Mountain"
};
item["OrderStatus"] = new AttributeValue
{
S = "ORDER RECEIVED"
};
/* no ShipmentTrackingId attribute */
putItemRequest = new PutItemRequest
{
TableName = tableName,
Item = item,
ReturnItemCollectionMetrics = "SIZE"
};
client.PutItem(putItemRequest);
item = new Dictionary();
item["CustomerId"] = new AttributeValue
{
S = "alice@example.com"
};
item["OrderId"] = new AttributeValue
{
N = "3"
};
/* no IsOpen attribute */
item["OrderCreationDate"] = new AttributeValue
{
N = "20130304"
};
item["ProductCategory"] = new AttributeValue
{
S = "Music"
};
item["ProductName"] = new AttributeValue
{
S = "A Quiet Interlude"
};
item["OrderStatus"] = new AttributeValue
{
S = "IN TRANSIT"
};
item["ShipmentTrackingId"] = new AttributeValue
{
S = "176493"
};
putItemRequest = new PutItemRequest
{
TableName = tableName,
Item = item,
ReturnItemCollectionMetrics = "SIZE"
};
client.PutItem(putItemRequest);
item = new Dictionary();
item["CustomerId"] = new AttributeValue
{
S = "bob@example.com"
};
item["OrderId"] = new AttributeValue
{
N = "1"
};
/* no IsOpen attribute */
item["OrderCreationDate"] = new AttributeValue
{
N = "20130111"
};
item["ProductCategory"] = new AttributeValue
{
S = "Movie"
};
item["ProductName"] = new AttributeValue
{
S = "Calm Before The Storm"
};
item["OrderStatus"] = new AttributeValue
{
S = "SHIPPING DELAY"
};
item["ShipmentTrackingId"] = new AttributeValue
{
S = "859323"
};
putItemRequest = new PutItemRequest
{
TableName = tableName,
Item = item,
ReturnItemCollectionMetrics = "SIZE"
};
client.PutItem(putItemRequest);
item = new Dictionary();
item["CustomerId"] = new AttributeValue
{
S = "bob@example.com"
};
item["OrderId"] = new AttributeValue
{
N = "2"
};
/* no IsOpen attribute */
item["OrderCreationDate"] = new AttributeValue
{
N = "20130124"
};
item["ProductCategory"] = new AttributeValue
{
S = "Music"
};
item["ProductName"] = new AttributeValue
{
S = "E-Z Listening"
};
item["OrderStatus"] = new AttributeValue
{
S = "DELIVERED"
};
item["ShipmentTrackingId"] = new AttributeValue
{
S = "756943"
};
putItemRequest = new PutItemRequest
{
TableName = tableName,
Item = item,
ReturnItemCollectionMetrics = "SIZE"
};
client.PutItem(putItemRequest);
item = new Dictionary();
item["CustomerId"] = new AttributeValue
{
S = "bob@example.com"
};
item["OrderId"] = new AttributeValue
{
N = "3"
};
/* no IsOpen attribute */
item["OrderCreationDate"] = new AttributeValue
{
N = "20130221"
};
item["ProductCategory"] = new AttributeValue
{
S = "Music"
};
item["ProductName"] = new AttributeValue
{
S = "Symphony 9"
};
item["OrderStatus"] = new AttributeValue
{
S = "DELIVERED"
};
item["ShipmentTrackingId"] = new AttributeValue
{
S = "645193"
};
putItemRequest = new PutItemRequest
{
TableName = tableName,
Item = item,
ReturnItemCollectionMetrics = "SIZE"
};
client.PutItem(putItemRequest);
item = new Dictionary();
item["CustomerId"] = new AttributeValue
{
S = "bob@example.com"
};
item["OrderId"] = new AttributeValue
{
N = "4"
};
item["IsOpen"] = new AttributeValue
{
N = "1"
};
item["OrderCreationDate"] = new AttributeValue
{
N = "20130222"
};
item["ProductCategory"] = new AttributeValue
{
S = "Hardware"
};
item["ProductName"] = new AttributeValue
{
S = "Extra Heavy Hammer"
};
item["OrderStatus"] = new AttributeValue
{
S = "PACKING ITEMS"
};
/* no ShipmentTrackingId attribute */
putItemRequest = new PutItemRequest
{
TableName = tableName,
Item = item,
ReturnItemCollectionMetrics = "SIZE"
};
client.PutItem(putItemRequest);
item = new Dictionary();
item["CustomerId"] = new AttributeValue
{
S = "bob@example.com"
};
item["OrderId"] = new AttributeValue
{
N = "5"
};
/* no IsOpen attribute */
item["OrderCreationDate"] = new AttributeValue
{
N = "20130309"
};
item["ProductCategory"] = new AttributeValue
{
S = "Book"
};
item["ProductName"] = new AttributeValue
{
S = "How To Cook"
};
item["OrderStatus"] = new AttributeValue
{
S = "IN TRANSIT"
};
item["ShipmentTrackingId"] = new AttributeValue
{
S = "440185"
};
putItemRequest = new PutItemRequest
{
TableName = tableName,
Item = item,
ReturnItemCollectionMetrics = "SIZE"
};
client.PutItem(putItemRequest);
item = new Dictionary();
item["CustomerId"] = new AttributeValue
{
S = "bob@example.com"
};
item["OrderId"] = new AttributeValue
{
N = "6"
};
/* no IsOpen attribute */
item["OrderCreationDate"] = new AttributeValue
{
N = "20130318"
};
item["ProductCategory"] = new AttributeValue
{
S = "Luggage"
};
item["ProductName"] = new AttributeValue
{
S = "Really Big Suitcase"
};
item["OrderStatus"] = new AttributeValue
{
S = "DELIVERED"
};
item["ShipmentTrackingId"] = new AttributeValue
{
S = "893927"
};
putItemRequest = new PutItemRequest
{
TableName = tableName,
Item = item,
ReturnItemCollectionMetrics = "SIZE"
};
client.PutItem(putItemRequest);
item = new Dictionary();
item["CustomerId"] = new AttributeValue
{
S = "bob@example.com"
};
item["OrderId"] = new AttributeValue
{
N = "7"
};
/* no IsOpen attribute */
item["OrderCreationDate"] = new AttributeValue
{
N = "20130324"
};
item["ProductCategory"] = new AttributeValue
{
S = "Golf"
};
item["ProductName"] = new AttributeValue
{
S = "PGA Pro II"
};
item["OrderStatus"] = new AttributeValue
{
S = "OUT FOR DELIVERY"
};
item["ShipmentTrackingId"] = new AttributeValue
{
S = "383283"
};
putItemRequest = new PutItemRequest
{
TableName = tableName,
Item = item,
ReturnItemCollectionMetrics = "SIZE"
};
client.PutItem(putItemRequest);
}
private static void WaitUntilTableReady(string tableName)
{
string status = null;
// Let us wait until table is created. Call DescribeTable.
do
{
System.Threading.Thread.Sleep(5000); // Wait 5 seconds.
try
{
var res = client.DescribeTable(new DescribeTableRequest
{
TableName = tableName
});
Console.WriteLine("Table name: {0}, status: {1}",
res.Table.TableName,
res.Table.TableStatus);
status = res.Table.TableStatus;
}
catch (ResourceNotFoundException)
{
// DescribeTable is eventually consistent. So you might
// get resource not found. So we handle the potential exception.
}
} while (status != "ACTIVE");
}
private static void WaitForTableToBeDeleted(string tableName)
{
bool tablePresent = true;
while (tablePresent)
{
System.Threading.Thread.Sleep(5000); // Wait 5 seconds.
try
{
var res = client.DescribeTable(new DescribeTableRequest
{
TableName = tableName
});
Console.WriteLine("Table name: {0}, status: {1}",
res.Table.TableName,
res.Table.TableStatus);
}
catch (ResourceNotFoundException)
{
tablePresent = false;
}
}
}
}
}
```
# Utilisation d’index secondaires locaux dans la AWS CLI de DynamoDB
Vous pouvez utiliser AWS CLI pour créer une table Amazon DynamoDB avec un ou plusieurs index secondaires locaux, décrire les index sur la table, et effectuer des requêtes à l’aide des index.
**Topics**
+ [Créer une table avec un index secondaire local](#LCICli.CreateTableWithIndex)
+ [Décrire une table avec un index secondaire local](#LCICli.DescribeTableWithIndex)
+ [Interroger un index secondaire local](#LCICli.QueryAnIndex)
## Créer une table avec un index secondaire local
Vous devez créer des index secondaires locaux au moment où vous créez une table. Pour ce faire, utilisez le paramètre `create-table` et fournissez vos spécifications pour un ou plusieurs index secondaires locaux. L’exemple suivant crée une table (`Music`) destinée à accueillir des données informations sur des chansons dans une collection musicale. La clé de partition est `Artist`, et la clé de tri `SongTitle`. Un index secondaire, `AlbumTitleIndex`, sur l’attribut `AlbumTitle` facilite les requêtes par titre d’album.
```
aws dynamodb create-table \
--table-name Music \
--attribute-definitions AttributeName=Artist,AttributeType=S AttributeName=SongTitle,AttributeType=S \
AttributeName=AlbumTitle,AttributeType=S \
--key-schema AttributeName=Artist,KeyType=HASH AttributeName=SongTitle,KeyType=RANGE \
--provisioned-throughput \
ReadCapacityUnits=10,WriteCapacityUnits=5 \
--local-secondary-indexes \
"[{\"IndexName\": \"AlbumTitleIndex\",
\"KeySchema\":[{\"AttributeName\":\"Artist\",\"KeyType\":\"HASH\"},
{\"AttributeName\":\"AlbumTitle\",\"KeyType\":\"RANGE\"}],
\"Projection\":{\"ProjectionType\":\"INCLUDE\", \"NonKeyAttributes\":[\"Genre\", \"Year\"]}}]"
```
Vous devez attendre que DynamoDB crée la table et définisse l’état de celle-ci sur `ACTIVE`. Après cela, vous pouvez commencer à insérer des éléments de données dans la table. Vous pouvez utiliser la commande [describe-table](https://docs.aws.amazon.com/cli/latest/reference/dynamodb/describe-table.html) pour déterminer l’état de la création de table.
## Décrire une table avec un index secondaire local
Pour obtenir des informations concernant les index secondaires locaux sur une table, utilisez le paramètre `describe-table`. Pour chaque index, vous pouvez accéder à son nom, à son schéma de clé et aux attributs projetés.
```
aws dynamodb describe-table --table-name Music
```
## Interroger un index secondaire local
Vous pouvez utiliser l’opération `query` sur un index secondaire local de la même manière que vous utilisez l’opération `query` sur une table. Vous devez spécifier le nom d’index, les critères de requête pour la clé de tri d’index et les attributs que vous souhaitez renvoyer. Dans cet exemple, l’index est `AlbumTitleIndex` et la clé de tri d’index est `AlbumTitle`.
Les seuls attributs renvoyés sont ceux qui ont été projetés dans l’index. Vous pourriez également modifier cette requête pour sélectionner des attributs autres que de clé, mais cela nécessiterait une activité d’extraction de table relativement coûteuse. Pour plus d’informations sur les extractions de table, consultez [Projections d’attribut](LSI.md#LSI.Projections).
```
aws dynamodb query \
--table-name Music \
--index-name AlbumTitleIndex \
--key-condition-expression "Artist = :v_artist and AlbumTitle = :v_title" \
--expression-attribute-values '{":v_artist":{"S":"Acme Band"},":v_title":{"S":"Songs About Life"} }'
```
# Gestion des flux complexes avec des transactions Amazon DynamoDB
Les transactions Amazon DynamoDB simplifient l'expérience des développeurs en apportant des modifications coordonnées all-or-nothing à plusieurs éléments à la fois au sein des tables et entre elles. Les transactions introduisent l’atomicité, la cohérence, l’isolation et la durabilité (ACID) dans DynamoDB, ce qui permet de maintenir facilement l’exactitude des données dans vos applications.
Vous pouvez utiliser la lecture et l' APIs écriture transactionnelles DynamoDB pour gérer des flux de travail métier complexes qui nécessitent l'ajout, la mise à jour ou la suppression de plusieurs éléments en une seule opération. all-or-nothing Par exemple, un développeur de jeux vidéo peut ainsi s’assurer que les profils des joueurs sont mis à jour correctement lorsqu’ils échangent des objets ou effectuent des achats dans un jeu.
Avec l’API d’écriture de transaction, vous pouvez regrouper plusieurs actions `Put`, `Update`, `Delete` et `ConditionCheck`. Ensuite, vous pouvez soumettre les actions comme une seule opération `TransactWriteItems` qui réussit ou échoue en tant qu’unité. Il en va de même avec les actions `Get`, que vous pouvez regrouper et soumettre en une seule opération `TransactGetItems`.
L’activation des transactions pour vos tables DynamoDB n’occasionne pas de frais supplémentaires . Vous ne payez que pour les lectures ou écritures qui font partie de votre transaction. DynamoDB effectue deux lectures ou écritures sous-jacentes de chaque élément faisant partie de la transaction : l’une pour préparer la transaction, l’autre pour la valider. Ces deux read/write opérations sous-jacentes sont visibles dans vos CloudWatch statistiques Amazon.
Pour commencer à utiliser les transactions DynamoDB, téléchargez le AWS dernier SDK ou le (). AWS Command Line Interface AWS CLI Suivez ensuite l’[Exemple de transactions DynamoDB](transaction-example.md).
Les sections suivantes fournissent un aperçu détaillé de la transaction APIs et de la manière dont vous pouvez les utiliser dans DynamoDB.
**Topics**
+ [Comment ça marche](transaction-apis.md)
+ [Utilisation d’IAM avec des transactions](transaction-apis-iam.md)
+ [Exemple de code](transaction-example.md)
# Fonctionnement de transactions Amazon DynamoDB
Avec les transactions Amazon DynamoDB, vous pouvez regrouper plusieurs actions et les soumettre sous forme d'une all-or-nothing `TransactWriteItems` seule opération. `TransactGetItems` Les sections suivantes décrivent les opérations d’API, la gestion de la capacité, les bonnes pratiques et d’autres détails concernant l’utilisation des opérations transactionnelles dans DynamoDB.
**Topics**
+ [TransactWriteItems API](#transaction-apis-txwriteitems)
+ [TransactGetItems API](#transaction-apis-txgetitems)
+ [Niveaux d’isolement pour les transactions DynamoDB](#transaction-isolation)
+ [Gestion des conflits de transactions dans DynamoDB](#transaction-conflict-handling)
+ [Utilisation du mode transactionnel APIs dans DynamoDB Accelerator (DAX)](#transaction-apis-dax)
+ [Gestion de capacité pour les transactions](#transaction-capacity-handling)
+ [Bonnes pratiques en matière de transactions](#transaction-best-practices)
+ [Utilisation du mode transactionnel APIs avec des tables globales](#transaction-integration)
+ [Transactions DynamoDB par rapport à la bibliothèque cliente de transactions AWSLabs](#transaction-vs-library)
## TransactWriteItems API
`TransactWriteItems`est une opération d'écriture synchrone et idempotente qui regroupe jusqu'à 100 actions d'écriture en une seule opération. all-or-nothing Ces actions peuvent cibler jusqu'à 100 éléments distincts dans une ou plusieurs tables DynamoDB au sein du AWS même compte et de la même région. La taille d’agrégation des éléments dans la transaction ne peut pas dépasser 4 Mo. Les actions sont exécutées de manière atomique, de sorte qu’elles réussissent toutes ou aucune ne réussit.
**Note**
Une opération `TransactWriteItems` diffère d’une opération `BatchWriteItem` en ceci que toutes les actions qui y sont contenues doivent réussir, faute de quoi aucune modification du tout n’est apportée. Avec une opération `BatchWriteItem`, il est possible que certaines actions du lot seulement réussissent, alors que d’autres échouent.
Les transactions ne peuvent pas être effectuées au moyen d’index
Vous ne pouvez pas cibler le même élément avec plusieurs opérations contenues dans la même transaction. Par exemple, vous ne pouvez pas effectuer un `ConditionCheck` et une action `Update` sur le même élément de la même transaction.
Vous pouvez ajouter les types d’actions suivants à une transaction :
+ `Put` – Lance une opération `PutItem` pour créer un élément ou remplacer un ancien élément par un nouveau, de manière conditionnelle ou sans spécifier de condition.
+ `Update` – Lance une opération `UpdateItem` pour modifier les attributs d’un élément existant, ou ajouter un élément à la table s’il n’existe pas. Utilisez cette action pour ajouter, supprimer ou mettre à jour des attributs d’un élément existant, avec ou sans conditions.
+ `Delete` – Lance une opération `DeleteItem` pour supprimer un élément unique d’une table identifiée par sa clé primaire.
+ `ConditionCheck` – Vérifie l’existence d’un élément ou l’état d’attributs spécifiques de celui-ci.
Lorsqu'une transaction est terminée dans DynamoDB, ses modifications commencent à se propager aux index secondaires globaux GSIs (), aux flux et aux sauvegardes. Cette propagation se produit progressivement : les enregistrements de flux d’une même transaction peuvent s’afficher à des moments différents et s’entrelacer avec des enregistrements d’autres transactions. Les consommateurs de flux ne doivent pas présumer de l’atomicité des transactions ou des garanties d’ordre.
Pour garantir un instantané atomique des éléments modifiés lors d'une transaction, utilisez l' TransactGetItems opération pour lire tous les éléments pertinents ensemble. Cette opération fournit une vue cohérente des données, vous permettant soit de voir toutes les modifications apportées à une transaction terminée, soit de n’en voir aucune.
La propagation n'étant pas immédiate, si une table est restaurée à partir de backup ([RestoreTableFromBackup](https://docs.aws.amazon.com/amazondynamodb/latest/APIReference/API_RestoreTableFromBackup.html)) ou exportée à un point dans le temps ([ExportTableToPointInTime](https://docs.aws.amazon.com/amazondynamodb/latest/APIReference/API_ExportTableToPointInTime.html)) en cours de propagation, elle ne peut contenir que certaines des modifications apportées lors d'une transaction récente.
### Idempotence
En option, vous pouvez inclure un jeton client lorsque vous faites un appel `TransactWriteItems` afin de garantir l’*idempotence* de la demande. Des transactions idempotentes évitent des erreurs d’application si la même opération est soumise plusieurs fois suite à une expiration de la connexion ou à tout autre problème de connectivité.
Si l’appel initial de `TransactWriteItems` réussit, les appels suivants de `TransactWriteItems` avec le même jeton client aboutissent sans apporter aucune modification. Si le paramètre `ReturnConsumedCapacity` est défini, l’appel `TransactWriteItems` initial renvoie le nombre d’unités de capacité en écriture consommées par l’exécution de ces modifications. Les appels `TransactWriteItems` subséquents avec le même jeton client renvoient le nombre d’unités de capacité en lecture consommées par la lecture de l’élément.
**Considérations importantes concernant l’idempotence**
+ Un jeton client est valide pendant 10 minutes après la fin de la demande qui l’utilise. Après 10 minutes, toute demande utilisant le même jeton client est traitée comme une nouvelle demande. Évitez donc de réutiliser le même jeton client pour la même demande après 10 minutes.
+ Si vous répétez une demande avec le même jeton client dans la fenêtre d’idempotence de 10 minutes, mais modifiez un autre paramètre de demande, DynamoDB renvoie une exception `IdempotentParameterMismatch`.
### Gestion des erreurs d’écriture
Les transactions d’écriture échouent dans les conditions suivantes :
+ Lorsqu’une condition d’une des expressions de condition n’est pas remplie.
+ Lorsqu’une erreur de validation de la transaction se produit parce que plusieurs actions de la même opération `TransactWriteItems` ciblent le même élément.
+ Lorsqu’une demande `TransactWriteItems` est en conflit avec une opération `TransactWriteItems` en cours sur un ou plusieurs éléments dans la demande `TransactWriteItems`. Dans ce cas, la demande échoue avec une exception `TransactionCanceledException`.
+ Lorsque la capacité allouée est insuffisante pour achever la transaction.
+ Lorsqu’un élément devient trop volumineux (plus de 400 ko), qu’un index secondaire local (LSI) devient trop volumineux ou qu’une erreur de validation similaire se produit en raison de modifications effectuées par la transaction.
+ En cas d’erreur de la part de l’utilisateur, par exemple un format de données incorrect.
Pour en savoir plus sur la gestion des conflits avec les opérations `TransactWriteItems`, consultez [Gestion des conflits de transactions dans DynamoDB](#transaction-conflict-handling).
## TransactGetItems API
`TransactGetItems` est une opération de lecture synchrone qui regroupe jusqu’à 100 actions `Get`. Ces actions peuvent cibler jusqu'à 100 éléments distincts dans une ou plusieurs tables DynamoDB au sein d'un même compte et d'une AWS même région. La taille d’agrégation des éléments dans la transaction ne peut pas dépasser 4 Mo.
Les actions `Get` sont exécutées de manière atomique, de sorte qu’elles réussissent toutes ou échouent toutes.
+ `Get` – Lance une opération `GetItem` afin d’extraire un ensemble d’attributs pour l’élément avec la clé primaire donnée. Si aucun élément correspondant n’est trouvé, `Get` ne renvoie pas de données.
### Gestion des erreurs de lecture
Les transactions de lecture échouent dans les conditions suivantes :
+ Lorsqu’une demande `TransactGetItems` est en conflit avec une opération `TransactWriteItems` en cours sur un ou plusieurs éléments dans la demande `TransactGetItems`. Dans ce cas, la demande échoue avec une exception `TransactionCanceledException`.
+ Lorsque la capacité allouée est insuffisante pour achever la transaction.
+ En cas d’erreur de la part de l’utilisateur, par exemple un format de données incorrect.
Pour en savoir plus sur la gestion des conflits avec les opérations `TransactGetItems`, consultez [Gestion des conflits de transactions dans DynamoDB](#transaction-conflict-handling).
## Niveaux d’isolement pour les transactions DynamoDB
Les niveaux d’isolement des opérations transactionnelles (`TransactWriteItems` ou `TransactGetItems`) et autres opérations sont les suivants.
### SERIALIZABLE
Un isolement *sérialisable* assure que les résultats de plusieurs opérations concourantes sont les mêmes que si aucune opération ne commençait avant que la précédente soit terminée.
Il y a un isolement sérialisable entre les types d’opérations suivants :
+ Entre toute opération transactionnelle et toute opération d’écriture standard (`PutItem`, `UpdateItem` ou `DeleteItem`).
+ Entre toute opération transactionnelle et toute opération de lecture standard (`GetItem`).
+ Entre une opération `TransactWriteItems` et une opération `TransactGetItems`.
Bien qu’il y ait un isolement sérialisable entre les opérations transactionnelles et chaque écriture individuelle d’une opération `BatchWriteItem`, il n’y en a pas entre la transaction et l’opération `BatchWriteItem` en tant qu’ensemble.
De même, le niveau d’isolation entre une opération transactionnelle et un `GetItems` dans une opération `BatchGetItem` est sérialisable. Mais le niveau d’isolation entre la transaction et l’opération `BatchGetItem` en tant qu’unité est *read-committed*.
Une demande `GetItem` unique est sérialisable par rapport à une demande `TransactWriteItems` de deux façons, avant ou après la demande `TransactWriteItems`. Plusieurs demandes `GetItem` par rapport à des clés dans une demande `TransactWriteItems` simultanée peuvent s’exécuter dans n’importe quel ordre. C’est pourquoi les résultats sont *validés en lecture*.
Par exemple, si des demandes `GetItem` pour des éléments A et B sont exécutées en même temps qu’une demande `TransactWriteItems` qui modifie les éléments A et B, il y a quatre possibilités :
+ Les deux demandes `GetItem` sont exécutées avant la demande `TransactWriteItems`.
+ Les deux demandes `GetItem` sont exécutées après la demande `TransactWriteItems`.
+ La demande `GetItem` pour l’élément A est exécutée avant la demande `TransactWriteItems`. Pour l’élément B, la demande `GetItem` est exécutée après la demande `TransactWriteItems`.
+ La demande `GetItem` pour l’élément B est exécutée avant la demande `TransactWriteItems`. Pour l’élément A, la demande `GetItem` est exécutée après la demande `TransactWriteItems`.
Vous devez utiliser la demande `TransactGetItems` si vous préférez un niveau d’isolement sérialisable pour plusieurs demandes `GetItem`.
Si une lecture non transactionnelle est effectuée sur plusieurs éléments faisant partie de la même demande d’écriture de transaction en cours, il est possible que vous puissiez lire le nouvel état de certains éléments et l’ancien état des autres éléments. Vous pouvez lire le nouvel état de tous les éléments qui faisaient partie de la demande d’écriture de transaction seulement en cas de réception d’une réponse de réussite de l’écriture de transaction indiquant que la transaction est terminée.
Une fois la transaction effectuée et la réponse reçue, les opérations ultérieures de lecture *cohérente à terme* peuvent toujours renvoyer l’ancien état pendant une courte période en raison du modèle de cohérence à terme de DynamoDB. Pour garantir la lecture du plus grand up-to-date nombre de données immédiatement après une transaction, vous devez utiliser des lectures [*très cohérentes*](HowItWorks.ReadConsistency.md#HowItWorks.ReadConsistency.Strongly) en définissant le paramètre `ConsistentRead` sur true.
### READ-COMMITTED
L’isolement *validé en lecture* garantit que les opérations de lecture renvoient toujours des valeurs validées pour un élément. La lecture ne présentera jamais une vue de l’élément représentant un état issu d’une écriture transactionnelle qui n’a pas abouti. Un isolement validé en lecture n’empêche pas des modifications de l’élément juste après la lecture.
Le niveau d’isolement est validé en lecture entre toute opération transactionnelle et toute opération de lecture impliquant plusieurs lectures standard (`BatchGetItem`, `Query` ou `Scan`). Si une écriture transactionnelle met à jour un élément au milieu d’une opération `BatchGetItem`, `Query` ou `Scan`, la partie suivante de l’opération de lecture renvoie la valeur nouvellement validée (avec `ConsistentRead)` ou éventuellement une valeur déjà validée (lectures éventuellement cohérentes).
### Résumé des opérations
Pour résumer, le tableau qui suit montre les niveaux d’isolement entre une opération transactionnelle (`TransactWriteItems` ou `TransactGetItems`) et d’autres opérations :
| Opération | Niveau d’isolement |
| --- | --- |
| `DeleteItem` | *Sérialisable* |
| `PutItem` | *Sérialisable* |
| `UpdateItem` | *Sérialisable* |
| `GetItem` | *Sérialisable* |
| `BatchGetItem` | *Validé en lecture*\$1 |
| `BatchWriteItem` | *NON sérialisable*\$1 |
| `Query` | *Validé en lecture* |
| `Scan` | *Validé en lecture* |
| Autre opération transactionnelle | *Sérialisable* |
Les niveaux marqués d’un astérisque (\$1) s’appliquent à l’opération dans son ensemble. Toutefois, les actions individuelles au sein de ces opérations ont un niveau d’isolement *sérialisable*.
## Gestion des conflits de transactions dans DynamoDB
Un conflit transactionnel peut se produire lors de demandes simultanées au niveau de l’élément sur un élément au sein d’une transaction. Les conflits de transaction peuvent se produire dans les scénarios suivants :
+ Une requête `PutItem`, `UpdateItem` ou `DeleteItem` pour un élément est en conflit avec une requête `TransactWriteItems` en cours qui inclut le même élément.
+ Un élément au sein d’une requête `TransactWriteItems` fait partie d’une autre requête `TransactWriteItems` en cours.
+ Un élément au sein d’une requête `TransactGetItems` fait partie d’une autre requête `TransactWriteItems`, `BatchWriteItem`, `PutItem`, `UpdateItem` ou `DeleteItem` en cours.
**Note**
Quand une requête `PutItem`, `UpdateItem` ou `DeleteItem` est rejetée, la requête échoue avec un code `TransactionConflictException`.
Si toute requête au niveau de l’élément au sein de `TransactWriteItems` ou `TransactGetItems` est rejetée, la requête échoue avec un code `TransactionCanceledException`. Si cette demande échoue, AWS SDKs ne réessayez pas.
Si vous utilisez le AWS SDK pour Java, l'exception contient la liste de [CancellationReasons](https://docs.aws.amazon.com/amazondynamodb/latest/APIReference/API_CancellationReason.html), ordonnée en fonction de la liste des éléments du paramètre de `TransactItems` demande. Pour d’autres langues, une représentation sous forme de chaîne de la liste est incluse dans le message d’erreur de l’exception.
Si une opération `TransactWriteItems` en cours ou une opération `TransactGetItems` est en conflit avec une demande `GetItem` concourante, les deux opérations peuvent réussir.
La [TransactionConflict CloudWatch métrique](https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/metrics-dimensions.html) est incrémentée pour chaque demande échouée au niveau de l'élément.
## Utilisation du mode transactionnel APIs dans DynamoDB Accelerator (DAX)
Les demandes `TransactWriteItems` et `TransactGetItems` sont toutes deux prises en charge dans DynamoDB Accelerator (DAX) avec les mêmes niveaux d’isolement que dans DynamoDB.
La demande `TransactWriteItems` écrit via DAX. DAX transmet un appel `TransactWriteItems` à DynamoDB et renvoie la réponse. Pour remplir le cache après l’écriture, DAX appelle `TransactGetItems` en arrière-plan pour chaque élément dans l’opération `TransactWriteItems`, qui consomme des unités de capacité de lecture supplémentaires. (Pour en savoir plus, consultez [Gestion de capacité pour les transactions](#transaction-capacity-handling).) Cette fonctionnalité vous permet de simplifier la logique de votre application et d’utiliser DAX pour les opérations transactionnelles et non transactionnelles.
Les appels `TransactGetItems` sont transmis via DAX sans les éléments mis en cache localement. Il s'agit du même comportement que pour une lecture très cohérente APIs dans DAX.
## Gestion de capacité pour les transactions
L'activation des transactions pour vos tables DynamoDB n'occasionne pas de frais supplémentaires . Vous ne payez que pour les lectures ou écritures qui font partie de votre transaction. DynamoDB effectue deux lectures ou écritures sous-jacentes de chaque élément faisant partie de la transaction : l’une pour préparer la transaction, l’autre pour la valider. Les deux read/write opérations sous-jacentes sont visibles dans vos CloudWatch statistiques Amazon.
Planifiez les lectures et écritures supplémentaires requises par le protocole transactionnel APIs lorsque vous allouez de la capacité à vos tables. Par exemple, supposons que votre application exécute une transaction par seconde et que chaque transaction écrit trois éléments de 500 octets dans votre table. Chaque article nécessite deux unités de capacité d'écriture (WCUs) : une pour préparer la transaction et une pour valider la transaction. Par conséquent, vous devez en fournir six WCUs à la table.
Si vous utilisiez DynamoDB Accelerator (DAX) dans l'exemple précédent, vous utiliseriez également deux unités de capacité de lecture RCUs () pour chaque élément de l'appel. `TransactWriteItems` Vous devrez donc en prévoir six supplémentaires RCUs à la table.
De même, si votre application exécute une transaction de lecture par seconde et que chaque transaction lit trois éléments de 500 octets dans votre table, vous devez fournir six unités de capacité de lecture (RCUs) à la table. La lecture de chaque élément en nécessite deux RCUs : un pour préparer la transaction et un pour valider la transaction.
En outre, le comportement par défaut du SDK est de ressayer les transactions en cas d’exception `TransactionInProgressException`. Prévoyez les unités de capacité de lecture supplémentaires (RCUs) consommées par ces nouvelles tentatives. Il en va de même si vous réessayez des transactions dans votre propre code à l’aide d’un `ClientRequestToken`.
## Bonnes pratiques en matière de transactions
Lorsque vous utilisez des transactions DynamoDB, prenez en compte les bonnes pratiques recommandées suivantes.
+ Activez la scalabilité automatique sur vos tables ou veillez à allouer suffisamment de capacité de débit pour effectuer les deux opérations de lecture et écriture pour chaque élément de votre transaction.
+ Si vous n'utilisez pas le SDK AWS fourni, incluez un `ClientRequestToken` attribut lorsque vous effectuez un `TransactWriteItems` appel pour vous assurer que la demande est idempotente.
+ Ne regroupez pas d’opérations en une transaction si ce n’est pas nécessaire. Par exemple, si une transaction unique avec 10 opérations peut être subdivisée en plusieurs transactions sans compromettre l’exactitude de l’application, nous recommandons de scinder la transaction. Des transactions plus simples améliorent le débit et sont plus susceptibles de réussir.
+ Si plusieurs transactions mettent à jour simultanément les mêmes éléments, il peut y avoir des conflits qui annulent ces transactions. Nous recommandons de suivre les bonnes pratiques DynamoDB en matière de modélisation des données pour minimiser de tels conflits.
+ Si un ensemble d’attributs est souvent mis à jour sur plusieurs éléments dans le cadre d’une seule et même transaction, envisagez de regrouper les attributs dans un seul élément afin de réduire la portée de la transaction.
+ Évitez d’utiliser des transactions pour ingérer des données en masse. Pour les écritures en masse, il est préférable d’utiliser `BatchWriteItem`.
## Utilisation du mode transactionnel APIs avec des tables globales
Les opérations transactionnelles fournissent des garanties d'atomicité, de cohérence, d'isolation et de durabilité (ACID) uniquement dans la AWS région où l'API d'écriture a été invoquée. Les transactions des tables globales ne sont pas prises en charge dans toutes les régions. Par exemple, supposons que vous disposiez d’une table globale avec des réplicas dans les régions USA Est (Ohio) et USA Ouest (Oregon) et que vous effectuiez une opération `TransactWriteItems` dans la région USA Est (Virginie du Nord). Vous risquez d’observer des transactions partiellement terminées dans la région USA Ouest (Oregon) lorsque les modifications sont répliquées. Les modifications ne sont répliquées dans les autres régions qu’une fois validées dans la région source.
## Transactions DynamoDB par rapport à la bibliothèque cliente de transactions AWSLabs
Les transactions DynamoDB constituent un remplacement plus rentable, plus robuste et plus performant de [AWSLabs](https://github.com/awslabs)la bibliothèque cliente de transactions. Nous vous suggérons de mettre à jour vos applications pour utiliser la transaction native côté serveur. APIs
# Utilisation d’IAM avec des transactions DynamoDB
Vous pouvez utiliser Gestion des identités et des accès AWS (IAM) pour restreindre les actions que les opérations transactionnelles peuvent effectuer dans Amazon DynamoDB. Pour en savoir plus sur l’utilisation de politiques IAM dans DynamoDB, consultez [Politiques basées sur l’identité pour DynamoDB](security_iam_service-with-iam.md#security_iam_service-with-iam-id-based-policies).
Les autorisations pour `Put`, `Update`, `Delete` et `Get` sont régies par celle utilisées pour les opérations `PutItem`, `UpdateItem`, `DeleteItem` et `GetItem` sous-jacentes. Pour l’action `ConditionCheck`, vous pouvez utiliser l’autorisation `dynamodb:ConditionCheckItem` dans des politiques IAM.
Vous trouverez ci-dessous des exemples de politiques IAM que vous pouvez utiliser pour configurer des transactions DynamoDB.
## Exemple 1 : autoriser les opérations transactionnelles
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"dynamodb:ConditionCheckItem",
"dynamodb:PutItem",
"dynamodb:UpdateItem",
"dynamodb:DeleteItem",
"dynamodb:GetItem"
],
"Resource": [
"arn:aws:dynamodb:*:*:table/table04"
]
}
]
}
```
------
## Exemple 2 : autoriser uniquement les opérations transactionnelles
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"dynamodb:ConditionCheckItem",
"dynamodb:PutItem",
"dynamodb:UpdateItem",
"dynamodb:DeleteItem",
"dynamodb:GetItem"
],
"Resource": [
"arn:aws:dynamodb:*:*:table/table04"
],
"Condition": {
"ForAnyValue:StringEquals": {
"dynamodb:EnclosingOperation": [
"TransactWriteItems",
"TransactGetItems"
]
}
}
}
]
}
```
------
## Exemple 3 : autoriser les lectures et écritures non transactionnelles, bloquer les lectures et écritures transactionnelles
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Deny",
"Action": [
"dynamodb:ConditionCheckItem",
"dynamodb:PutItem",
"dynamodb:UpdateItem",
"dynamodb:DeleteItem",
"dynamodb:GetItem"
],
"Resource": [
"arn:aws:dynamodb:*:*:table/table04"
],
"Condition": {
"ForAnyValue:StringEquals": {
"dynamodb:EnclosingOperation": [
"TransactWriteItems",
"TransactGetItems"
]
}
}
},
{
"Effect": "Allow",
"Action": [
"dynamodb:PutItem",
"dynamodb:DeleteItem",
"dynamodb:GetItem",
"dynamodb:UpdateItem"
],
"Resource": [
"arn:aws:dynamodb:*:*:table/table04"
]
}
]
}
```
------
## Exemple 4 : Empêcher le renvoi d'informations en ConditionCheck cas de panne
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"dynamodb:ConditionCheckItem",
"dynamodb:PutItem",
"dynamodb:UpdateItem",
"dynamodb:DeleteItem",
"dynamodb:GetItem"
],
"Resource": "arn:aws:dynamodb:*:*:table/table01",
"Condition": {
"StringEqualsIfExists": {
"dynamodb:ReturnValues": "NONE"
}
}
}
]
}
```
------
# Exemple de transactions DynamoDB
A titre d'exemple de situation dans laquelle des transactions Amazon DynamoDB peuvent être utiles, considérez cette application Java pour une place de marché en ligne.
L'application dispose de trois tables DynamoDB dans le backend :
+ `Customers` – Cette table stocke des détails sur les clients de la place de marché. Sa clé primaire est un identifiant unique `CustomerId`.
+ `ProductCatalog` – Ce tableau stocke des détails tels que le prix et la disponibilité des produits en vente sur la place de marché. Sa clé primaire est un identifiant unique `ProductId`.
+ `Orders` – Cette table stocke des détails sur les commandes en provenance de la place de marché. Sa clé primaire est un identifiant unique `OrderId`.
## Passation d'une commande
Les extraits de code suivants montrent comment utiliser des transactions DynamoDB pour coordonner les différentes étapes de la création et du traitement d'une commande. L'utilisation d'une seule all-or-nothing opération garantit qu'en cas d'échec d'une partie de la transaction, aucune action de la transaction n'est exécutée et aucune modification n'est apportée.
Dans cet exemple, vous configurez une commande à partir d'un client dont le `customerId` est `09e8e9c8-ec48`. Vous l'exécutez ensuite en tant que transaction unique à l'aide du simple flux de traitement de commandes suivant :
1. Déterminez si l'ID client est valide.
1. Assurez-vous que l'état du produit est `IN_STOCK` et mettez à jour son état en `SOLD`.
1. Assurez-vous que la commande n'existe pas déjà, puis créez la commande.
### Valider le client
Commencez par définir une action pour vérifier qu'un client avec `customerId` égal à `09e8e9c8-ec48` existe dans la table client.
```
final String CUSTOMER_TABLE_NAME = "Customers";
final String CUSTOMER_PARTITION_KEY = "CustomerId";
final String customerId = "09e8e9c8-ec48";
final HashMap customerItemKey = new HashMap<>();
customerItemKey.put(CUSTOMER_PARTITION_KEY, new AttributeValue(customerId));
ConditionCheck checkCustomerValid = new ConditionCheck()
.withTableName(CUSTOMER_TABLE_NAME)
.withKey(customerItemKey)
.withConditionExpression("attribute_exists(" + CUSTOMER_PARTITION_KEY + ")");
```
### Mettre à jour l'état du produit
Ensuite, définissez une action pour mettre à jour l'état du produit sur `SOLD` si la condition que l'état du produit soit actuellement défini sur `IN_STOCK` est `true`. La définition du paramètre `ReturnValuesOnConditionCheckFailure` a pour effet de renvoyer l'article si l'attribut d'état de produit de celui-ci n'est pas `IN_STOCK`.
```
final String PRODUCT_TABLE_NAME = "ProductCatalog";
final String PRODUCT_PARTITION_KEY = "ProductId";
HashMap productItemKey = new HashMap<>();
productItemKey.put(PRODUCT_PARTITION_KEY, new AttributeValue(productKey));
Map expressionAttributeValues = new HashMap<>();
expressionAttributeValues.put(":new_status", new AttributeValue("SOLD"));
expressionAttributeValues.put(":expected_status", new AttributeValue("IN_STOCK"));
Update markItemSold = new Update()
.withTableName(PRODUCT_TABLE_NAME)
.withKey(productItemKey)
.withUpdateExpression("SET ProductStatus = :new_status")
.withExpressionAttributeValues(expressionAttributeValues)
.withConditionExpression("ProductStatus = :expected_status")
.withReturnValuesOnConditionCheckFailure(ReturnValuesOnConditionCheckFailure.ALL_OLD);
```
### Créer la commande
Enfin, créez la commande pour autant qu'il n'existe pas de commande avec cet `OrderId`.
```
final String ORDER_PARTITION_KEY = "OrderId";
final String ORDER_TABLE_NAME = "Orders";
HashMap orderItem = new HashMap<>();
orderItem.put(ORDER_PARTITION_KEY, new AttributeValue(orderId));
orderItem.put(PRODUCT_PARTITION_KEY, new AttributeValue(productKey));
orderItem.put(CUSTOMER_PARTITION_KEY, new AttributeValue(customerId));
orderItem.put("OrderStatus", new AttributeValue("CONFIRMED"));
orderItem.put("OrderTotal", new AttributeValue("100"));
Put createOrder = new Put()
.withTableName(ORDER_TABLE_NAME)
.withItem(orderItem)
.withReturnValuesOnConditionCheckFailure(ReturnValuesOnConditionCheckFailure.ALL_OLD)
.withConditionExpression("attribute_not_exists(" + ORDER_PARTITION_KEY + ")");
```
### Exécuter la transaction
L'exemple suivant montre comment exécuter les actions définies précédemment en une seule all-or-nothing opération.
```
Collection actions = Arrays.asList(
new TransactWriteItem().withConditionCheck(checkCustomerValid),
new TransactWriteItem().withUpdate(markItemSold),
new TransactWriteItem().withPut(createOrder));
TransactWriteItemsRequest placeOrderTransaction = new TransactWriteItemsRequest()
.withTransactItems(actions)
.withReturnConsumedCapacity(ReturnConsumedCapacity.TOTAL);
// Run the transaction and process the result.
try {
client.transactWriteItems(placeOrderTransaction);
System.out.println("Transaction Successful");
} catch (ResourceNotFoundException rnf) {
System.err.println("One of the table involved in the transaction is not found" + rnf.getMessage());
} catch (InternalServerErrorException ise) {
System.err.println("Internal Server Error" + ise.getMessage());
} catch (TransactionCanceledException tce) {
System.out.println("Transaction Canceled " + tce.getMessage());
}
```
## Lecture des détails de la commande
L'exemple suivant montre comment lire la commande terminée de manière transactionnelle dans les tables `Orders` et `ProductCatalog`.
```
HashMap productItemKey = new HashMap<>();
productItemKey.put(PRODUCT_PARTITION_KEY, new AttributeValue(productKey));
HashMap orderKey = new HashMap<>();
orderKey.put(ORDER_PARTITION_KEY, new AttributeValue(orderId));
Get readProductSold = new Get()
.withTableName(PRODUCT_TABLE_NAME)
.withKey(productItemKey);
Get readCreatedOrder = new Get()
.withTableName(ORDER_TABLE_NAME)
.withKey(orderKey);
Collection getActions = Arrays.asList(
new TransactGetItem().withGet(readProductSold),
new TransactGetItem().withGet(readCreatedOrder));
TransactGetItemsRequest readCompletedOrder = new TransactGetItemsRequest()
.withTransactItems(getActions)
.withReturnConsumedCapacity(ReturnConsumedCapacity.TOTAL);
// Run the transaction and process the result.
try {
TransactGetItemsResult result = client.transactGetItems(readCompletedOrder);
System.out.println(result.getResponses());
} catch (ResourceNotFoundException rnf) {
System.err.println("One of the table involved in the transaction is not found" + rnf.getMessage());
} catch (InternalServerErrorException ise) {
System.err.println("Internal Server Error" + ise.getMessage());
} catch (TransactionCanceledException tce) {
System.err.println("Transaction Canceled" + tce.getMessage());
}
```
# Récupération de données de modification avec Amazon DynamoDB
Bon nombre d’applications bénéficient de la récupération des modifications apportées aux éléments stockés dans une table DynamoDB au moment elles se produisent. Voici quelques exemples de cas d’utilisation.
+ Une application mobile populaire modifie des données dans une table DynamoDB au rythme de milliers de mises à jour par seconde. Une autre application capture et stocke les données relatives à ces mises à jour, fournissant des mesures near-real-time d'utilisation pour l'application mobile.
+ Une application financière modifie des données boursières dans une table DynamoDB. Différentes applications exécutées en parallèle suivent ces changements en temps réel value-at-risk, calculent et rééquilibrent automatiquement les portefeuilles en fonction de l'évolution du cours des actions.
+ Des capteurs dans des véhicules de transport et des équipements industriels envoient des données à une table DynamoDB. Différentes applications contrôlent les performances et envoient des alertes par messagerie lors de la détection d’un problème, prédisent des défaillances potentielles en appliquant des algorithmes de machine learning, et compressent et archivent les données dans Amazon Simple Storage Service (Amazon S3).
+ Une application envoie automatiquement des notifications sur les appareils mobiles de tous les amis dans un groupe dès qu’un ami télécharge une nouvelle image.
+ Un nouveau client ajoute des données à une table DynamoDB. Cet événement appelle une autre application qui envoie un e-mail de bienvenue au nouveau client.
DynamoDB prend en charge le streaming des enregistrements de récupération de données de modification au niveau élément en quasi-temps réel. Vous pouvez créer des applications qui consomment ces flux et entreprennent des actions basées sur le contenu.
**Note**
L’ajout de balises à DynamoDB Streams et l’utilisation du [contrôle d’accès par attributs (ABAC)](access-control-resource-based.md) avec DynamoDB Streams ne sont pas pris en charge.
La vidéo suivante vous présente le concept de capture des données de modification.
[](http://www.youtube.com/watch?v=https://www.youtube.com/embed/VVv_-mZ5Ge8)
**Topics**
+ [Options de streaming pour la récupération de données de modification](#streamsmain.choose)
+ [Utilisation de Kinesis Data Streams pour récupérer les modifications apportées à DynamoDB](kds.md)
+ [Modifier la récupération de données pour DynamoDB Streams](Streams.md)
## Options de streaming pour la récupération de données de modification
DynamoDB offre deux modèles de streaming pour la récupération de données de modification : Kinesis Data Streams pour DynamoDB et DynamoDB Streams.
Afin de vous aider à choisir la solution appropriée pour votre application, le tableau suivant récapitule les fonctions de chaque modèle de streaming.
[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/fr_fr/amazondynamodb/latest/developerguide/streamsmain.html)
Vous pouvez activer les deux modèles de streaming sur la même table DynamoDB.
La vidéo suivante évoque plus en détail les différences entre les deux options.
[](http://www.youtube.com/watch?v=https://www.youtube.com/embed/UgG17Wh2y0g)
# Utilisation de Kinesis Data Streams pour récupérer les modifications apportées à DynamoDB
Vous pouvez utiliser Amazon Kinesis Data Streams pour capturer les modifications apportées à Amazon DynamoDB.
Kinesis Data Streams récupère les modifications au niveau élément dans n’importe quelle table DynamoDB et les réplique dans un [flux de données Kinesis](https://docs.aws.amazon.com/streams/latest/dev/introduction.html) de votre choix. Vos applications peuvent accéder à ce flux et afficher les modifications au niveau élément en quasi-temps réel. Vous pouvez récupérer et stocker en continu des téraoctets de données par heure. Vous pouvez profiter d’un temps de conservation des données plus long et, grâce à une capacité de déploiement améliorée, vous pouvez atteindre simultanément deux applications en aval ou plus. Les autres avantages incluent des audits et une transparence de sécurité supplémentaires.
Kinesis Data Streams vous donne également accès à [Amazon Data Firehose](https://docs.aws.amazon.com/firehose/latest/dev/what-is-this-service.html) et au [service géré Amazon pour Apache Flink](https://docs.aws.amazon.com/kinesisanalytics/latest/dev/what-is.html). Ces services peuvent vous aider à créer des applications qui alimentent des tableaux de bord en temps réel, génèrent des alertes, implémentent une tarification et une publicité dynamiques, et mettent en œuvre une analytique des données sophistiquée et des algorithmes de machine learning.
**Note**
[L'utilisation des flux de données Kinesis pour DynamoDB est soumise à la fois à la tarification Kinesis Data Streams pour le flux de [données et à la tarification DynamoDB pour](https://aws.amazon.com/kinesis/data-streams/pricing/) la table source.](https://aws.amazon.com/dynamodb/pricing/)
Pour activer le streaming Kinesis sur une table DynamoDB à l'aide de la console ou du SDK Java AWS CLI, consultez. [Prise en main de Kinesis Data Streams pour Amazon DynamoDB](kds_gettingstarted.md)
**Topics**
+ [Comment Kinesis Data Streams fonctionne avec DynamoDB](#kds_howitworks)
+ [Prise en main de Kinesis Data Streams pour Amazon DynamoDB](kds_gettingstarted.md)
+ [Utilisation de partitions et de métriques avec DynamoDB Streams et Kinesis Data Streams](kds_using-shards-and-metrics.md)
+ [Utilisation de politiques IAM personnalisées pour Amazon Kinesis Data Streams et Amazon DynamoDB](kds_iam.md)
## Comment Kinesis Data Streams fonctionne avec DynamoDB
Lorsqu’un flux de données Kinesis est activé pour une table DynamoDB, la table envoie un enregistrement de données qui récupère toutes les modifications apportées aux données de cette table. Cet enregistrement de données comprend :
+ L’heure spécifique à laquelle un élément a été récemment créé, mis à jour ou supprimé
+ La clé primaire de cet élément
+ Un instantané de l’enregistrement avant la modification
+ Un instantané de l’enregistrement après la modification
Ces enregistrements de données sont capturés et publiés en quasi-temps réel. Une fois écrits dans le flux de données Kinesis, ils peuvent être lus comme tout autre enregistrement. Vous pouvez utiliser la bibliothèque cliente Kinesis, utiliser AWS Lambda, appeler l'API Kinesis Data Streams et utiliser d'autres services connectés. Pour en savoir plus, consultez [Lecture de données à partir d’Amazon Kinesis Data Streams](https://docs.aws.amazon.com/streams/latest/dev/building-consumers.html) dans le Guide du développeur Amazon Kinesis Data Streams.
Ces modifications apportées aux données sont également récupérées de manière asynchrone. Kinesis n’a aucun impact sur les performances d’une table depuis laquelle elle est diffusée en continu. Les enregistrements de flux stockés dans votre flux de données Kinesis sont aussi chiffrés au repos. Pour en savoir plus, consultez [Protection des données dans Amazon Kinesis Data Streams](https://docs.aws.amazon.com/streams/latest/dev/server-side-encryption.html).
Les enregistrements de flux de données Kinesis peuvent s’afficher dans un ordre différent de celui dans lequel les modifications des éléments ont eu lieu. Les mêmes notifications d’éléments peuvent également apparaître plusieurs fois dans le flux. Vous pouvez vérifier l’attribut `ApproximateCreationDateTime` pour identifier l’ordre dans lequel les modifications des éléments ont eu lieu et les enregistrements en double.
Lorsque vous activez un flux de données Kinesis comme destination de streaming d’une table DynamoDB, vous pouvez configurer la précision des valeurs `ApproximateCreationDateTime` en millisecondes ou microsecondes. Par défaut, `ApproximateCreationDateTime` indique l’heure de la modification en millisecondes. De plus, vous pouvez modifier cette valeur sur une destination de streaming active. Après cette mise à jour, les enregistrements de flux écrits dans Kinesis ont des valeurs `ApproximateCreationDateTime` de la précision souhaitée.
Les valeurs binaires écrites dans DynamoDB doivent être codées au [format codé en base64](HowItWorks.NamingRulesDataTypes.md). Toutefois, lorsque des enregistrements de données sont écrits dans un flux de données Kinesis, ces valeurs binaires codées sont codées une deuxième fois avec un codage base64. Lorsqu’il s’agit de lire ces enregistrements à partir d’un flux de données Kinesis, pour récupérer les valeurs binaires brutes, les applications doivent décoder ces valeurs deux fois.
DynamoDB facture l’utilisation de Kinesis Data Streams en unités de capture de données de modification. 1 Ko de modification par élément unique est considéré comme une unité de capture de données de modification. Le Ko de modification dans chaque élément est calculé par la plus grande des images « avant » et « après » de l’élément écrit dans le flux, en utilisant la même logique que [la consommation d’unités de capacité pour les opérations d’écriture](read-write-operations.md#write-operation-consumption). Comme pour le fonctionnement du mode [à la demande](capacity-mode.md#capacity-mode-on-demand) de DynamoDB, vous n’aurez pas besoin d’allouer le débit de capacité pour les unités de capture des données de modification.
### Activer un flux de données Kinesis pour votre table DynamoDB
Vous pouvez activer ou désactiver le streaming vers Kinesis à partir de votre table DynamoDB existante à l'aide du AWS SDK ou du AWS Management Console(). AWS Command Line Interface AWS CLI
+ Vous ne pouvez diffuser des données de DynamoDB vers Kinesis Data Streams que dans le même AWS compte et dans AWS la même région que votre table.
+ Vous pouvez uniquement diffuser des données depuis une table DynamoDB vers un flux de données Kinesis.
### Modification d’une destination Kinesis Data Streams de votre table DynamoDB
Par défaut, tous les enregistrements de flux de données Kinesis incluent un attribut `ApproximateCreationDateTime`. Cet attribut représente un horodatage en millisecondes de l’heure approximative à laquelle chaque enregistrement a été créé. Vous pouvez modifier la précision de ces valeurs à l'aide du fichier [https://console.aws.amazon.com/kinesis](https://console.aws.amazon.com/kinesis), du SDK ou du AWS CLI
# Prise en main de Kinesis Data Streams pour Amazon DynamoDB
Cette section explique comment utiliser les tables Kinesis Data Streams pour Amazon DynamoDB avec la console Amazon DynamoDB, le () et l'API. AWS Command Line Interface AWS CLI
## Création d’un flux de données Amazon Kinesis actif
Tous ces exemples utilisent la table DynamoDB `Music` créée dans le cadre du tutoriel [Mise en route avec DynamoDB](https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/GettingStartedDynamoDB.html).
Pour en savoir plus sur la façon de créer des consommateurs et de connecter votre flux de données Kinesis à d’autres services AWS , consultez [Lecture de données à partir de Kinesis Data Streams](https://docs.aws.amazon.com/streams/latest/dev/building-consumers.html) dans le *Guide du développeur Amazon Kinesis Data Streams*.
**Note**
Lorsque vous utilisez les partitions KDS pour la première fois, nous vous recommandons de les configurer de manière à ce que leur capacité s’adapte à la hausse ou à la baisse en fonction de vos modèles d’utilisation. Une fois que vous aurez accumulé davantage de données sur les modèles d’utilisation, vous pourrez ajuster les partitions de votre flux en conséquence.
------
#### [ Console ]
1. Connectez-vous à la console Kinesis AWS Management Console et ouvrez-la à l'adresse. [https://console.aws.amazon.com/kinesis/](https://console.aws.amazon.com/kinesis/)
1. Choisissez **Create data stream (Créer un flux de données)**, puis suivez les instructions pour créer un flux appelé `samplestream`.
1. Ouvrez la console DynamoDB à l'adresse. [https://console.aws.amazon.com/dynamodb/](https://console.aws.amazon.com/dynamodb/)
1. Dans le volet de navigation sur le côté gauche de la console, choisissez **Tables**.
1. Choisissez la table **Music**.
1. Choisissez l’onglet **Exportations et flux**.
1. (Facultatif) Sous **Informations sur le flux de données Amazon Kinesis**, vous pouvez modifier la précision de l’horodatage des enregistrements de microseconde (par défaut) à milliseconde.
1. Choisissez **samplestream** dans la liste déroulante.
1. Cliquez sur le bouton **Activer**.
------
#### [ AWS CLI ]
1. Créez un flux de données Kinesis nommé `samplestream` à l’aide de la [commande create-stream](https://docs.aws.amazon.com/cli/latest/reference/kinesis/create-stream.html).
```
aws kinesis create-stream --stream-name samplestream --shard-count 3
```
Consultez [Considérations relatives à la gestion des partitions pour Kinesis Data Streams](kds_using-shards-and-metrics.md#kds_using-shards-and-metrics.shardmanagment) avant de définir le nombre de partitions du flux de données Kinesis.
1. Vérifiez que le flux Kinesis est actif et prêt pour utilisation à l’aide de la [commande describe-stream](https://docs.aws.amazon.com/cli/latest/reference/kinesis/describe-stream.html).
```
aws kinesis describe-stream --stream-name samplestream
```
1. Activez le streaming Kinesis sur la table DynamoDB à l’aide de la commande DynamoDB `enable-kinesis-streaming-destination`. Remplacez la valeur `stream-arn` par celle que la commande `describe-stream` a renvoyée à l’étape précédente. Activez éventuellement le streaming avec une précision plus détaillée (microseconde) des valeurs d’horodatage renvoyées sur chaque enregistrement.
Activez le streaming avec une précision d’horodatage de l’ordre de la microseconde :
```
aws dynamodb enable-kinesis-streaming-destination \
--table-name Music \
--stream-arn arn:aws:kinesis:us-west-2:12345678901:stream/samplestream
--enable-kinesis-streaming-configuration ApproximateCreationDateTimePrecision=MICROSECOND
```
Ou activez le streaming avec la précision d’horodatage par défaut (milliseconde) :
```
aws dynamodb enable-kinesis-streaming-destination \
--table-name Music \
--stream-arn arn:aws:kinesis:us-west-2:12345678901:stream/samplestream
```
1. Vérifiez si le streaming Kinesis est actif sur la table à l’aide de la commande DynamoDB `describe-kinesis-streaming-destination`.
```
aws dynamodb describe-kinesis-streaming-destination --table-name Music
```
1. Écrivez des données dans la table DynamoDB à l’aide de la commande `put-item`, comme décrit dans le [Guide du développeur DynamoDB](https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/getting-started-step-2.html).
```
aws dynamodb put-item \
--table-name Music \
--item \
'{"Artist": {"S": "No One You Know"}, "SongTitle": {"S": "Call Me Today"}, "AlbumTitle": {"S": "Somewhat Famous"}, "Awards": {"N": "1"}}'
aws dynamodb put-item \
--table-name Music \
--item \
'{"Artist": {"S": "Acme Band"}, "SongTitle": {"S": "Happy Day"}, "AlbumTitle": {"S": "Songs About Life"}, "Awards": {"N": "10"} }'
```
1. Utilisez la commande CLI [get-records](https://docs.aws.amazon.com/cli/latest/reference/kinesis/get-records.html) de Kinesis pour extraire le contenu du flux Kinesis. Ensuite, utilisez l’extrait de code suivant pour désérialiser le contenu du flux.
```
/**
* Takes as input a Record fetched from Kinesis and does arbitrary processing as an example.
*/
public void processRecord(Record kinesisRecord) throws IOException {
ByteBuffer kdsRecordByteBuffer = kinesisRecord.getData();
JsonNode rootNode = OBJECT_MAPPER.readTree(kdsRecordByteBuffer.array());
JsonNode dynamoDBRecord = rootNode.get("dynamodb");
JsonNode oldItemImage = dynamoDBRecord.get("OldImage");
JsonNode newItemImage = dynamoDBRecord.get("NewImage");
Instant recordTimestamp = fetchTimestamp(dynamoDBRecord);
/**
* Say for example our record contains a String attribute named "stringName" and we want to fetch the value
* of this attribute from the new item image. The following code fetches this value.
*/
JsonNode attributeNode = newItemImage.get("stringName");
JsonNode attributeValueNode = attributeNode.get("S"); // Using DynamoDB "S" type attribute
String attributeValue = attributeValueNode.textValue();
System.out.println(attributeValue);
}
private Instant fetchTimestamp(JsonNode dynamoDBRecord) {
JsonNode timestampJson = dynamoDBRecord.get("ApproximateCreationDateTime");
JsonNode timestampPrecisionJson = dynamoDBRecord.get("ApproximateCreationDateTimePrecision");
if (timestampPrecisionJson != null && timestampPrecisionJson.equals("MICROSECOND")) {
return Instant.EPOCH.plus(timestampJson.longValue(), ChronoUnit.MICROS);
}
return Instant.ofEpochMilli(timestampJson.longValue());
}
```
------
#### [ Java ]
1. Suivez les instructions du Guide du développeur Kinesis Data Streams pour [créer](https://docs.aws.amazon.com/streams/latest/dev/kinesis-using-sdk-java-create-stream.html) un flux de données Kinesis nommé `samplestream` à l’aide de Java.
Consultez [Considérations relatives à la gestion des partitions pour Kinesis Data Streams](kds_using-shards-and-metrics.md#kds_using-shards-and-metrics.shardmanagment) avant de définir le nombre de partitions pour le flux de données Kinesis.
1. Utilisez l’extrait de code suivant pour activer le streaming Kinesis sur la table DynamoDB. Activez éventuellement le streaming avec une précision plus détaillée (microseconde) des valeurs d’horodatage renvoyées sur chaque enregistrement.
Activez le streaming avec une précision d’horodatage de l’ordre de la microseconde :
```
EnableKinesisStreamingConfiguration enableKdsConfig = EnableKinesisStreamingConfiguration.builder()
.approximateCreationDateTimePrecision(ApproximateCreationDateTimePrecision.MICROSECOND)
.build();
EnableKinesisStreamingDestinationRequest enableKdsRequest = EnableKinesisStreamingDestinationRequest.builder()
.tableName(tableName)
.streamArn(kdsArn)
.enableKinesisStreamingConfiguration(enableKdsConfig)
.build();
EnableKinesisStreamingDestinationResponse enableKdsResponse = ddbClient.enableKinesisStreamingDestination(enableKdsRequest);
```
Ou activez le streaming avec la précision d’horodatage par défaut (milliseconde) :
```
EnableKinesisStreamingDestinationRequest enableKdsRequest = EnableKinesisStreamingDestinationRequest.builder()
.tableName(tableName)
.streamArn(kdsArn)
.build();
EnableKinesisStreamingDestinationResponse enableKdsResponse = ddbClient.enableKinesisStreamingDestination(enableKdsRequest);
```
1. Suivez les instructions du *Guide du développeur Kinesis Data Streams* pour [lire](https://docs.aws.amazon.com/streams/latest/dev/building-consumers.html) le flux de données créé.
1. Utilisez l’extrait de code suivant pour désérialiser le contenu du flux
```
/**
* Takes as input a Record fetched from Kinesis and does arbitrary processing as an example.
*/
public void processRecord(Record kinesisRecord) throws IOException {
ByteBuffer kdsRecordByteBuffer = kinesisRecord.getData();
JsonNode rootNode = OBJECT_MAPPER.readTree(kdsRecordByteBuffer.array());
JsonNode dynamoDBRecord = rootNode.get("dynamodb");
JsonNode oldItemImage = dynamoDBRecord.get("OldImage");
JsonNode newItemImage = dynamoDBRecord.get("NewImage");
Instant recordTimestamp = fetchTimestamp(dynamoDBRecord);
/**
* Say for example our record contains a String attribute named "stringName" and we wanted to fetch the value
* of this attribute from the new item image, the below code would fetch this.
*/
JsonNode attributeNode = newItemImage.get("stringName");
JsonNode attributeValueNode = attributeNode.get("S"); // Using DynamoDB "S" type attribute
String attributeValue = attributeValueNode.textValue();
System.out.println(attributeValue);
}
private Instant fetchTimestamp(JsonNode dynamoDBRecord) {
JsonNode timestampJson = dynamoDBRecord.get("ApproximateCreationDateTime");
JsonNode timestampPrecisionJson = dynamoDBRecord.get("ApproximateCreationDateTimePrecision");
if (timestampPrecisionJson != null && timestampPrecisionJson.equals("MICROSECOND")) {
return Instant.EPOCH.plus(timestampJson.longValue(), ChronoUnit.MICROS);
}
return Instant.ofEpochMilli(timestampJson.longValue());
}
```
------
## Modification d’un flux de données Amazon Kinesis actif
Cette section décrit comment apporter des modifications à une configuration Kinesis Data Streams pour DynamoDB active à l'aide de la console et de l'API. AWS CLI
**AWS Management Console**
1. Ouvrez la console DynamoDB à l'adresse [https://console.aws.amazon.com/dynamodb/](https://console.aws.amazon.com/dynamodb/)
1. Accédez à votre table.
1. Choisissez l’onglet **Exportations et flux**.
**AWS CLI**
1. Appelez `describe-kinesis-streaming-destination` pour vérifier que le stream est `ACTIVE`.
1. Appelez `UpdateKinesisStreamingDestination`, comme dans cet exemple :
```
aws dynamodb update-kinesis-streaming-destination --table-name enable_test_table --stream-arn arn:aws:kinesis:us-east-1:12345678901:stream/enable_test_stream --update-kinesis-streaming-configuration ApproximateCreationDateTimePrecision=MICROSECOND
```
1. Appelez `describe-kinesis-streaming-destination` pour vérifier que le stream est `UPDATING`.
1. Appelez `describe-kinesis-streaming-destination` régulièrement jusqu’à ce que le statut de streaming redevienne `ACTIVE`. Les mises à jour de précision de l’horodatage prennent effet généralement sous 5 minutes. Une fois ce statut mis à jour, cela indique que la mise à jour est terminée et que la nouvelle valeur de précision sera appliquée aux futurs enregistrements.
1. Écrivez dans la table à l’aide de `putItem`.
1. Utilisez la commande `get-records` de Kinesis pour récupérer le contenu du flux.
1. Vérifiez que la valeur `ApproximateCreationDateTime` des écritures possède la précision souhaitée.
**API Java**
1. Fournissez un extrait de code qui construit une demande `UpdateKinesisStreamingDestination` et une réponse `UpdateKinesisStreamingDestination`.
1. Fournissez un extrait de code qui construit une demande `DescribeKinesisStreamingDestination` et une réponse `DescribeKinesisStreamingDestination response`.
1. Appelez `describe-kinesis-streaming-destination` régulièrement jusqu’à ce que le statut de streaming redevienne `ACTIVE`, indiquant que la mise à jour est terminée et que la nouvelle valeur de précision sera appliquée aux futurs enregistrements.
1. Effectuez des écritures sur la table.
1. Lisez le flux et désérialisez son contenu.
1. Vérifiez que la valeur `ApproximateCreationDateTime` des écritures possède la précision souhaitée.
# Utilisation de partitions et de métriques avec DynamoDB Streams et Kinesis Data Streams
## Considérations relatives à la gestion des partitions pour Kinesis Data Streams
Un flux de données Kinesis compte son débit dans les [partitions](https://docs.aws.amazon.com/streams/latest/dev/key-concepts.html). Dans Amazon Kinesis Data Streams, vous pouvez choisir entre le mode **à la demande** et le mode **provisionné** pour vos flux de données.
Nous vous recommandons d’utiliser le mode à la demande pour votre flux de données Kinesis si votre charge de travail d’écriture DynamoDB est très variable et imprévisible. En mode à la demande, aucune planification de la capacité n’est nécessaire, car Kinesis Data Streams gère automatiquement les partitions afin de fournir le débit nécessaire.
En cas de charges de travail prévisibles, vous pouvez utiliser le mode provisionné pour votre flux de données Kinesis. En mode provisionné, vous devez spécifier le nombre de partitions du flux de données nécessaires pour accueillir les enregistrements de capture des données de modification provenant de DynamoDB. Pour déterminer le nombre de partitions dont le flux de données Kinesis aura besoin pour prendre en charge votre table DynamoDB, vous devez disposer des valeurs d’entrée suivantes :
+ Taille moyenne d’enregistrement de votre table DynamoDB en octets (`average_record_size_in_bytes`).
+ Nombre maximum d’opérations d’écriture que votre table DynamoDB effectuera par seconde. Ce nombre inclut les opérations de création, de suppression et de mise à jour effectuées par vos applications, ainsi que les opérations générées automatiquement, comme les opérations de suppression générées par Time-to-Live (`write_throughput`).
+ Pourcentage d’opérations de mise à jour et de remplacement que vous effectuez sur votre table par rapport aux opérations de création ou de suppression (`percentage_of_updates`). N’oubliez pas que les opérations de mise à jour et de remplacement répliquent les anciennes et les nouvelles images de l’élément modifié dans le flux. Elles génèrent ainsi deux fois la taille de l’élément DynamoDB.
Vous pouvez calculer le nombre de partitions (`number_of_shards`) dont votre flux de données Kinesis a besoin à l’aide des valeurs d’entrée de la formule suivante :
```
number_of_shards = ceiling( max( ((write_throughput * (4+percentage_of_updates) * average_record_size_in_bytes) / 1024 / 1024), (write_throughput/1000)), 1)
```
Par exemple, vous pouvez avoir un débit maximal de 1 040 opérations d’écriture par seconde (`write_throughput`) avec une taille d’enregistrement moyenne de 800 octets (`average_record_size_in_bytes)`. Si 25 % de ces opérations d’écriture sont des opérations de mise à jour (`percentage_of_updates`), vous aurez besoin de deux partitions (`number_of_shards`) pour accueillir votre débit de streaming DynamoDB :
```
ceiling( max( ((1040 * (4+25/100) * 800)/ 1024 / 1024), (1040/1000)), 1).
```
Tenez compte des points suivants avant d’utiliser la formule de calcul du nombre de partitions requises en mode provisionné pour les flux de données Kinesis :
+ Cette formule permet d’estimer le nombre de partitions nécessaires pour accueillir vos enregistrements de données de modification DynamoDB. Elle ne représente pas le nombre total de partitions dont votre flux de données Kinesis a besoin, comme le nombre de partitions requises pour prendre en charge des consommateurs de flux de données Kinesis supplémentaires.
+ Vous pouvez toujours rencontrer des exceptions de débit de lecture et d’écriture en mode provisionné si vous ne configurez pas votre flux de données pour gérer votre débit maximal. Dans ce cas, vous devez mettre à l’échelle manuellement votre flux de données pour l’adapter à votre trafic de données.
+ Cette formule prend en compte le gonflement supplémentaire généré par DynamoDB avant de diffuser les enregistrements de données du journal des modifications à Kinesis Data Streams.
Pour en savoir plus sur les modes de capacité de Kinesis Data Streams, consultez [Choix du mode de capacité du flux de données](https://docs.aws.amazon.com/streams/latest/dev/how-do-i-size-a-stream.html). Pour en savoir plus sur les différences tarifaires entre les différents modes de capacité, consultez la [Tarification d’Amazon Kinesis Data Streams](https://aws.amazon.com/kinesis/data-streams/pricing/).
## Surveiller la récupération de données de modification avec Kinesis Data Streams
DynamoDB fournit plusieurs indicateurs CloudWatch Amazon pour vous aider à surveiller la réplication de la capture des données de modification vers Kinesis. Pour une liste complète des CloudWatch indicateurs, voir[Métriques et dimensions DynamoDB](metrics-dimensions.md).
Afin de déterminer si votre flux dispose d’une capacité suffisante, nous vous recommandons de contrôler les éléments suivants, tant pendant l’activation du flux qu’en production :
+ `ThrottledPutRecordCount` : nombre d’enregistrements limités par votre flux de données Kinesis en raison d’une capacité insuffisante de flux de données Kinesis. La valeur `ThrottledPutRecordCount` devrait rester aussi basse que possible, quoique vous pourriez rencontrer une certaine limitation lors de pics d’utilisation exceptionnels. DynamoDB réessaie d’envoyer des enregistrements limités dans le flux de données Kinesis, mais cela peut engendrer une latence de réplication plus élevée.
Si vous rencontrez une limitation excessive et régulière, il se peut que vous deviez augmenter le nombre de partitions de flux Kinesis en proportion du débit d’écriture observé de votre table. Pour en savoir plus sur la détermination de la taille d’un flux de données Kinesis, consultez [Détermination de la taille initiale d’un flux de données Kinesis](https://docs.aws.amazon.com/streams/latest/dev/amazon-kinesis-streams.html#how-do-i-size-a-stream).
+ `AgeOfOldestUnreplicatedRecord` : temps écoulé depuis que la modification au niveau élément la plus ancienne restant à répliquer vers le flux de données Kinesis est apparue dans la table DynamoDB. Dans des conditions normales de fonctionnement, la valeur `AgeOfOldestUnreplicatedRecord` devrait être de l’ordre de quelques millisecondes. Ce nombre augmente en fonction des tentatives de réplication infructueuses, lorsque celles-ci sont causées par des choix de configuration contrôlés par le client.
Si la métrique `AgeOfOldestUnreplicatedRecord` dépasse 168 heures, la réplication des modifications apportées au niveau des éléments de la table DynamoDB dans le flux de données Kinesis est automatiquement désactivée.
Les configurations contrôlées par le client qui peuvent entraîner des tentatives de réplication infructueuses sont, par exemple, une capacité de flux de données Kinesis sous-allouée causant une limitation excessive ou une mise à jour manuelle des stratégies d’accès de votre flux de données Kinesis empêchant DynamoDB d’ajouter des données à votre flux de données. Vous devrez peut-être allouer une capacité de flux de données Kinesis suffisante et vous assurer que les autorisations de DynamoDB sont inchangées pour que cette métrique reste aussi faible que possible.
+ `FailedToReplicateRecordCount` : nombre d’enregistrements que DynamoDB n’a pas pu répliquer sur votre flux de données Kinesis. Certains éléments de plus de 34 Ko peuvent augmenter en taille pour modifier les enregistrements de données supérieurs à la limite de taille d’élément de 1 Mo de Kinesis Data Streams. Cette augmentation de taille se produit lorsque les éléments de plus de 34 Ko incluent un grand nombre de valeurs d’attribut booléennes ou vides. Les valeurs d’attribut booléennes et vides sont stockées sous la forme d’un octet dans DynamoDB. Toutefois, elles peuvent atteindre 5 octets lorsqu’elles sont sérialisées à l’aide de JSON standard pour la réplication Kinesis Data Streams. DynamoDB ne peut pas répliquer de tels enregistrements de modification dans votre flux de données Kinesis. DynamoDB ignore ces enregistrements de données de modification et continue automatiquement la réplication des enregistrements suivants.
Vous pouvez créer des CloudWatch alarmes Amazon qui envoient un message Amazon Simple Notification Service (Amazon SNS) pour notification lorsque l'une des mesures précédentes dépasse un seuil spécifique.
# Utilisation de politiques IAM personnalisées pour Amazon Kinesis Data Streams et Amazon DynamoDB
La première fois que vous activez Amazon Kinesis Data Streams pour Amazon DynamoDB, DynamoDB crée automatiquement Gestion des identités et des accès AWS un rôle lié à un service (IAM) pour vous. Ce rôle, `AWSServiceRoleForDynamoDBKinesisDataStreamsReplication`, permet à DynamoDB de gérer pour vous la réplication des modifications au niveau élément dans Kinesis Data Streams. Ne supprimez pas ce rôle lié à un service.
Pour en savoir plus sur l’utilisation des rôles liés à un service, consultez [Utilisation des rôles liés à un service](https://docs.aws.amazon.com/IAM/latest/UserGuide/using-service-linked-roles.html) dans le *Guide de l’utilisateur IAM*.
**Note**
DynamoDB ne prend pas en charge les conditions basées sur une balise pour les politiques IAM.
Pour activer Amazon Kinesis Data Streams pour Amazon DynamoDB, vous devez disposer des autorisations suivantes sur la table.
+ `dynamodb:EnableKinesisStreamingDestination`
+ `kinesis:ListStreams`
+ `kinesis:PutRecords`
+ `kinesis:DescribeStream`
Pour décrire Amazon Kinesis Data Streams pour Amazon DynamoDB pour une table DynamoDB donnée, vous devez disposer des autorisations suivantes sur la table.
+ `dynamodb:DescribeKinesisStreamingDestination`
+ `kinesis:DescribeStreamSummary`
+ `kinesis:DescribeStream`
Pour désactiver Amazon Kinesis Data Streams pour Amazon DynamoDB, vous devez disposer des autorisations suivantes sur la table.
+ `dynamodb:DisableKinesisStreamingDestination`
Pour mettre à jour Amazon Kinesis Data Streams pour Amazon DynamoDB, vous devez disposer des autorisations suivantes sur la table.
+ `dynamodb:UpdateKinesisStreamingDestination`
Les exemples suivants montrent comment utiliser des politiques IAM afin d’accorder des autorisations pour Amazon Kinesis Data Streams pour Amazon DynamoDB.
## Exemple : Activer Amazon Kinesis Data Streams pour Amazon DynamoDB
La politique IAM suivante octroie les autorisations nécessaires pour activer Amazon Kinesis Data Streams pour Amazon DynamoDB pour la table `Music`. Elle n’accorde pas les autorisations permettant de désactiver, de mettre à jour ou de décrire Kinesis Data Streams pour DynamoDB pour la table `Music`.
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": "iam:CreateServiceLinkedRole",
"Resource": "arn:aws:iam::*:role/aws-service-role/kinesisreplication.dynamodb.amazonaws.com/AWSServiceRoleForDynamoDBKinesisDataStreamsReplication",
"Condition": {
"StringLike": {
"iam:AWSServiceName": "kinesisreplication.dynamodb.amazonaws.com"
}
}
},
{
"Effect": "Allow",
"Action": [
"dynamodb:EnableKinesisStreamingDestination"
],
"Resource": "arn:aws:dynamodb:us-west-2:111122223333:table/Music"
}
]
}
```
------
## Exemple : mise à jour Amazon Kinesis Data Streams pour Amazon DynamoDB
La politique IAM suivante octroie les autorisations nécessaires pour mettre à jour Amazon Kinesis Data Streams pour Amazon DynamoDB pour la table `Music`. Elle n’accorde pas les autorisations permettant d’activer, de désactiver ou de décrire Amazon Kinesis Data Streams pour Amazon DynamoDB pour la table `Music`.
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"dynamodb:UpdateKinesisStreamingDestination"
],
"Resource": "arn:aws:dynamodb:us-west-2:111122223333:table/Music"
}
]
}
```
------
## Exemple : Désactiver Amazon Kinesis Data Streams pour Amazon DynamoDB
La politique IAM suivante octroie les autorisations nécessaires pour désactiver Amazon Kinesis Data Streams pour Amazon DynamoDB pour la table `Music`. Elle n’accorde pas les autorisations permettant d’activer, de mettre à jour ou de décrire Amazon Kinesis Data Streams pour Amazon DynamoDB pour la table `Music`.
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"dynamodb:DisableKinesisStreamingDestination"
],
"Resource": "arn:aws:dynamodb:us-west-2:111122223333:table/Music"
}
]
}
```
------
## Exemple : Appliquer de manière sélective des autorisations pour Amazon Kinesis Data Streams pour Amazon DynamoDB en fonction de la ressource
La politique IAM suivante octroie les autorisations nécessaires pour activer et décrire Amazon Kinesis Data Streams pour Amazon DynamoDB pour la table `Music`, et n’accorde pas les autorisations permettant de désactiver Amazon Kinesis Data Streams pour Amazon DynamoDB pour la table `Orders`.
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"dynamodb:EnableKinesisStreamingDestination",
"dynamodb:DescribeKinesisStreamingDestination"
],
"Resource": "arn:aws:dynamodb:us-west-2:111122223333:table/Music"
},
{
"Effect": "Deny",
"Action": [
"dynamodb:DisableKinesisStreamingDestination"
],
"Resource": "arn:aws:dynamodb:us-west-2:111122223333:table/Orders"
}
]
}
```
------
## Utilisation de rôles liés à un service pour Kinesis Data Streams pour DynamoDB
[Amazon Kinesis Data Streams pour Amazon Gestion des identités et des accès AWS DynamoDB utilise des rôles liés à un service (IAM).](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_terms-and-concepts.html#iam-term-service-linked-role) Un rôle lié à un service est un type unique de rôle IAM lié directement à Kinesis Data Streams pour DynamoDB. Les rôles liés à un service sont prédéfinis par Kinesis Data Streams for DynamoDB et incluent toutes les autorisations dont le service a besoin pour appeler d'autres services en votre nom. AWS
Un rôle lié à un service simplifie la configuration de Kinesis Data Streams pour DynamoDB, car vous n’avez pas besoin d’ajouter manuellement les autorisations nécessaires. Kinesis Data Streams pour DynamoDB définit les autorisations de ses rôles liés à un service et, sauf définition contraire, seul Kinesis Data Streams pour DynamoDB peut endosser ses rôles. Les autorisations définies comprennent la politique d’approbation et la politique d’autorisation. De plus, cette politique d’autorisation ne peut pas être attachée à une autre entité IAM.
Pour plus d'informations sur les autres services qui prennent en charge les rôles liés à un service, veuillez consulter [Services AWS qui fonctionnent avec IAM](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_aws-services-that-work-with-iam.html) et recherchez les services où **Oui **figure dans la colonne **Rôle lié à un service**. Choisissez un **Oui** ayant un lien permettant de consulter les détails du rôle pour ce service.
### Autorisations de rôle lié à un service pour Kinesis Data Streams pour DynamoDB
Kinesis Data Streams for DynamoDB utilise le rôle lié à un service nommé. **AWSServiceRoleForDynamoDBKinesisDataStreamsReplication** L’objectif du rôle lié à un service est d’autoriser Amazon DynamoDB à gérer pour vous la réplication des modifications au niveau élément dans Kinesis Data Streams.
Le rôle lié à un service `AWSServiceRoleForDynamoDBKinesisDataStreamsReplication` approuve les services suivants pour endosser le rôle :
+ `kinesisreplication.dynamodb.amazonaws.com`
La politique d’autorisations de rôle permet à Kinesis Data Streams pour DynamoDB d’accomplir les actions suivantes sur les ressources spécifiées :
+ Action : `Put records and describe` sur `Kinesis stream`
+ Action : `Generate data keys` activée pour placer les données `AWS KMS` dans les flux Kinesis chiffrés à l'aide de clés générées par l'utilisateur AWS KMS .
Pour le contenu exact du document de politique, voir [Dynamo. DBKinesis ReplicationServiceRolePolicy](https://console.aws.amazon.com/iam/home#policies/arn:aws:iam::aws:policy/aws-service-role/DynamoDBKinesisReplicationServiceRolePolicy)
Vous devez configurer les autorisations de manière à permettre à une entité IAM (comme un utilisateur, un groupe ou un rôle) de créer, modifier ou supprimer un rôle lié à un service. Pour en savoir plus, consultez [Service-Linked Role Permissions (autorisations du rôle lié à un service)](https://docs.aws.amazon.com/IAM/latest/UserGuide/contributorinsights-service-linked-roles.html#service-linked-role-permissions) dans le *Guide de l’utilisateur IAM*.
### Création d’un rôle lié à un service pour Kinesis Data Streams pour DynamoDB
Vous n’avez pas besoin de créer manuellement un rôle lié à un service. Lorsque vous activez Kinesis Data Streams pour DynamoDB dans, dans ou dans AWS Management Console l'API, AWS CLI AWS Kinesis Data Streams for DynamoDB crée pour vous le rôle lié au service.
Si vous supprimez ce rôle lié à un service et que vous avez ensuite besoin de le recréer, vous pouvez utiliser la même procédure pour recréer le rôle dans votre compte. Lorsque vous activez Kinesis Data Streams pour DynamoDB, le service crée pour vous le rôle lié à un service.
### Modification d’un rôle lié à un service pour Kinesis Data Streams pour DynamoDB
Kinesis Data Streams pour DynamoDB ne vous permet pas de modifier le rôle lié à un service `AWSServiceRoleForDynamoDBKinesisDataStreamsReplication`. Après avoir créé un rôle lié à un service, vous ne pouvez pas changer le nom du rôle, car plusieurs entités peuvent faire référence à ce rôle. Néanmoins, vous pouvez modifier la description du rôle à l’aide d’IAM. Pour en savoir plus, consultez [Modification d’un rôle lié à un service](https://docs.aws.amazon.com/IAM/latest/UserGuide/contributorinsights-service-linked-roles.html#edit-service-linked-role) dans le *Guide de l’utilisateur IAM*.
### Suppression d’un rôle lié à un service pour Kinesis Data Streams pour DynamoDB
Vous pouvez également utiliser la console IAM AWS CLI ou l' AWS API pour supprimer manuellement le rôle lié à un service. Pour ce faire, vous devez commencer par nettoyer les ressources de votre rôle lié à un service. Vous pouvez ensuite supprimer ce rôle manuellement.
**Note**
Si le service Kinesis Data Streams pour DynamoDB utilise le rôle lorsque vous essayez de supprimer les ressources, la suppression peut échouer. Si cela se produit, patientez quelques minutes et réessayez.
**Pour supprimer manuellement le rôle lié au service à l’aide d’IAM**
Utilisez la console IAM, le AWS CLI, ou l' AWS API pour supprimer le rôle lié au `AWSServiceRoleForDynamoDBKinesisDataStreamsReplication` service. Pour en savoir plus, consultez [Suppression d’un rôle lié à un service](https://docs.aws.amazon.com/IAM/latest/UserGuide/using-service-linked-roles.html) dans le *Guide de l’utilisateur IAM*.
# Modifier la récupération de données pour DynamoDB Streams
DynamoDB Streams récupère une séquence chronologique des modifications au niveau élément dans toute table DynamoDB et stocke ces informations dans un journal pendant jusqu’à 24 heures. Les applications ont accès à ce journal et affichent les éléments de données à mesure qu’ils s’affichent avant et après qu’ils ont été modifiés, pratiquement en temps réel.
Le chiffrement au repos chiffre les données dans les flux DynamoDB Streams. Pour en savoir plus, consultez [Chiffrement de DynamoDB au repos](EncryptionAtRest.md).
Un *flux DynamoDB* est un flux ordonné d’informations sur les modifications apportées aux éléments d’une table DynamoDB. Lorsque vous activez un flux sur une table, DynamoDB récupère des informations sur chaque modification apportée à des éléments de données dans la table.
Chaque fois qu’une application crée, met à jour ou supprime des éléments dans la table, DynamoDB Streams écrit un enregistrement de flux avec le ou les attributs de clé primaire des éléments qui ont été modifiés. Un *registre de flux* contient des informations sur une modification de données dans un seul élément d’une table DynamoDB. Vous pouvez configurer le flux de telle sorte que les enregistrements de flux récupèrent des informations supplémentaires, telles que les images « avant » et « après » d’éléments modifiés.
DynamoDB Streams permet de s’assurer de ce qui suit :
+ Chaque enregistrement de flux s’affiche exactement une fois dans le flux.
+ Pour chaque élément modifié dans une table DynamoDB, les enregistrements de flux apparaissent dans l’ordre des modifications réelles.
DynamoDB Streams écrit les enregistrements de flux en quasi-temps réel, afin que vous puissiez créer des applications qui consomment ces flux et entreprennent des actions basées sur le contenu.
**Topics**
+ [Points de terminaison pour DynamoDB Streams](#Streams.Endpoints)
+ [Activation d’un flux](#Streams.Enabling)
+ [Lecture et traitement de flux](#Streams.Processing)
+ [DynamoDB Streams et time-to-live](time-to-live-ttl-streams.md)
+ [Utilisation de l’adaptateur DynamoDB Streams Kinesis pour traiter des enregistrements de flux](Streams.KCLAdapter.md)
+ [API de bas niveau DynamoDB Streams : exemple Java](Streams.LowLevel.Walkthrough.md)
+ [Streams et déclencheurs DynamoDB AWS Lambda](Streams.Lambda.md)
+ [DynamoDB Streams et Apache Flink](StreamsApacheFlink.xml.md)
## Points de terminaison pour DynamoDB Streams
AWS gère des points de terminaison distincts pour DynamoDB et DynamoDB Streams. Pour utiliser des tables et index de base de données, votre application doit accéder à un point de terminaison DynamoDB. Pour lire et traiter des enregistrements DynamoDB Streams, votre application doit pouvoir accéder à un point de terminaison DynamoDB Streams dans la même région.
DynamoDB Streams propose deux ensembles de points de terminaison. Il s'agit des options suivantes :
+ **IPv4-points de terminaison uniquement : points** de terminaison dotés de la `streams.dynamodb..amazonaws.com` convention de dénomination.
+ **Points de terminaison à double pile** : nouveaux points de terminaison compatibles avec les deux IPv4 IPv6 et conformes à la `streams-dynamodb..api.aws` convention de dénomination.
**Note**
Pour accéder à la liste complète des régions et points de terminaison DynamoDB et DynamoDB Streams, consultez [Régions et points de terminaison](https://docs.aws.amazon.com/general/latest/gr/rande.html) dans *Références générales AWS*.
Ils AWS SDKs fournissent des clients distincts pour DynamoDB et DynamoDB Streams. En fonction de vos exigences, votre application peut accéder à un point de terminaison DynamoDB, un point de terminaison DynamoDB Streams, ou aux deux en même temps. Pour vous connecter aux deux points de terminaison, votre application doit instancier deux clients, l’un pour DynamoDB, et l’autre pour DynamoDB Streams.
## Activation d’un flux
Vous pouvez activer un flux sur une nouvelle table lorsque vous le créez à l'aide du AWS CLI ou de l'un des AWS SDKs. Vous pouvez également activer ou désactiver un flux sur une table existante, ou modifier les paramètres d’un flux. DynamoDB Streams opérant de manière asynchrone, l’activation d’un flux n’a aucune incidence sur les performances d’une table.
La manière la plus simple de gérer DynamoDB Streams consiste à utiliser l’ AWS Management Console.
1. Connectez-vous à la console DynamoDB AWS Management Console et ouvrez-la à l'adresse. [https://console.aws.amazon.com/dynamodb/](https://console.aws.amazon.com/dynamodb/)
1. Dans le tableau de bord de la console DynamoDB, choisissez **Tables**, puis sélectionnez une table.
1. Choisissez l’onglet **Exportations et flux**.
1. Dans la section **Détails du flux DynamoDB**, choisissez **Activer**.
1. Sur la page **Activer le flux DynamoDB**, choisissez les informations qui seront écrites dans le flux chaque fois que des données de la table seront modifiées :
+ **Attributs de clés uniquement** – Uniquement les attributs de clé de l’élément modifié.
+ **New image (Nouvelle image)** – L’élément entier, tel qu’il apparaît après sa modification.
+ **Old image (Ancienne image)** – L’élément entier, tel qu’il apparaissait avant sa modification.
+ **New and old images (Nouvelle et ancienne images)** – La nouvelle image et l’ancienne image de l’élément.
Lorsque les paramètres vous conviennent, choisissez **Activer le streaming**.
1. (Facultatif) Pour désactiver un flux existant, choisissez **Désactiver** sous **Détails du flux DynamoDB**.
Vous pouvez également utiliser les API `CreateTable` ou `UpdateTable` pour activer ou modifier un flux. Le paramètre `StreamSpecification` détermine la façon dont le flux est configuré :
+ `StreamEnabled` – Spécifique si un flux de données est activé (`true`) ou désactivé (`false`) pour la table.
+ `StreamViewType` – Spécifie les informations à écrire dans le flux à chaque modification des données de la table :
+ `KEYS_ONLY` – Uniquement les attributs de clé de l’élément modifié.
+ `NEW_IMAGE` – L’élément entier, tel qu’il apparaît après sa modification.
+ `OLD_IMAGE` – L’élément entier, tel qu’il apparaissait avant sa modification.
+ `NEW_AND_OLD_IMAGES` – La nouvelle image et l’ancienne image de l’élément.
Vous pouvez activer ou désactiver un flux à tout moment. Cependant, vous recevez un `ValidationException` si vous essayez d’activer un flux sur une table qui en possède déjà un. Vous recevez également un `ValidationException` si vous essayez de désactiver un flux sur une table qui n’en possède pas.
Lorsque vous définissez `StreamEnabled` sur `true`, DynamoDB crée un flux avec un descripteur de flux unique qui lui est attribué. Si vous désactivez et puis réactivez un flux sur la table, un flux est créé avec un descripteur de flux différent.
Chaque flux est identifié de manière unique par un Amazon Resource Name (ARN). Voici un exemple d’ARN pour un flux sur une table DynamoDB nommée `TestTable`.
```
arn:aws:dynamodb:us-west-2:111122223333:table/TestTable/stream/2015-05-11T21:21:33.291
```
Pour déterminer le dernier descripteur de flux pour une table, émettez une demande DynamoDB `DescribeTable`, puis recherchez l’élément `LatestStreamArn` dans la réponse.
**Note**
Il n’est pas possible de modifier un `StreamViewType` une fois qu’un flux a été configuré. Si vous devez apporter des modifications à un flux après sa configuration, vous devez désactiver le flux actuel et en créer un nouveau.
## Lecture et traitement de flux
Pour lire et traiter un flux, votre application doit se connecter à un point de terminaison DynamoDB Streams et émettre des demandes d’API.
Un flux se compose d’*enregistrements de flux*. Chaque enregistrement de flux représente une modification de donnée unique dans la table DynamoDB à laquelle le flux appartient. Chaque enregistrement de flux se voit attribuer un numéro de séquence, ce qui reflète l’ordre dans lequel l’enregistrement a été publié dans le flux.
Les enregistrements de flux sont organisés en groupes, ou *partitions*. Chaque partition agit comme un conteneur pour plusieurs enregistrements de flux et contient les informations requises pour accéder à ces enregistrements et les itérer. Les enregistrements de flux au sein d’une partition sont automatiquement supprimés au bout de 24 heures.
Les partitions sont éphémères. Elles sont créées et supprimées automatiquement, en fonction des besoins. Toute partition peut également se diviser en plusieurs partitions nouvelles. Cela se produit également automatiquement. (Notez qu’il est aussi possible pour une partition parent d’avoir une seule partition enfant). Une partition peut se diviser en réponse à des niveaux élevés d’activité d’écriture sur sa table parent, de telle sorte que les applications puissent traiter les enregistrements issus de plusieurs partitions en parallèle.
Si vous désactivez un flux, toute partition ouverte sera fermée. Les données du flux restent lisibles pendant 24 heures.
Comme les partitions ont une lignée (parent et enfants), une application doit toujours traiter une partition parent avant de traiter une partition enfant. Cela garantit que les enregistrements de flux sont également traités dans l’ordre adéquat. (Si vous utilisez l’adaptateur DynamoDB Streams Kinesis, cela est géré automatiquement. Votre application traite les partitions et les enregistrements de flux dans l’ordre correct. Elle gère automatiquement les partitions nouvelles ou ayant expiré, en plus des partitions qui ont été scindées pendant l’exécution de l’application. Pour plus d’informations, consultez [Utilisation de l’adaptateur DynamoDB Streams Kinesis pour traiter des enregistrements de flux](Streams.KCLAdapter.md).)
Le schéma suivant illustre la relation entre un flux de données, les partitions dans le flux et les enregistrements de flux dans les partitions.
![\[Structure de DynamoDB Streams. Les enregistrements de flux qui représentent des modifications de données sont organisés en partitions.\]](http://docs.aws.amazon.com/fr_fr/amazondynamodb/latest/developerguide/images/streams-terminology.png)
**Note**
Si vous effectuez une opération `PutItem` ou `UpdateItem` qui ne modifie aucune donnée dans un élément, DynamoDB Streams n’écrit *pas* d’enregistrement de flux pour cette opération.
Pour accéder à un flux de données et traiter les enregistrements de flux qu’il contient, vous devez effectuer les opérations suivantes :
+ Déterminer l’Amazon Resource Name (ARN) unique du flux auquel vous souhaitez accéder.
+ Déterminer quelles sont la ou les partitions du flux qui contiennent les enregistrements de flux qui vous intéressent.
+ Accéder aux partitions et récupérer les enregistrements de flux que vous voulez.
**Note**
Deux processus au maximum doivent lire simultanément à partir de la même partition de flux. Avoir plus de 2 lecteurs par partition peut entraîner une limitation.
L’API DynamoDB Streams fournit les actions suivantes à l’usage des programmes d’application :
+ `[ListStreams](https://docs.aws.amazon.com/amazondynamodb/latest/APIReference/API_streams_ListStreams.html)` – Renvoie la liste des descripteurs de flux pour le compte et le point de terminaison actuels. Vous pouvez en option demander uniquement les descripteurs de flux pour un nom de table particulier.
+ `[DescribeStream](https://docs.aws.amazon.com/amazondynamodb/latest/APIReference/API_streams_DescribeStream.html)` – Renvoie des informations sur un flux, y compris le statut actuel du flux, son Amazon Resource Name (ARN), la composition de ses partitions et sa table DynamoDB correspondante. Vous pouvez éventuellement récupérer la partition enfant associée à la partition parent à l’aide du champ `ShardFilter`.
+ `[GetShardIterator](https://docs.aws.amazon.com/amazondynamodb/latest/APIReference/API_streams_GetShardIterator.html)` – Renvoie un *itérateur de partition* décrivant un emplacement au sein d’une partition. Vous pouvez demander que l’itérateur fournisse un accès au point le plus ancien, au point le plus récent ou à un point particulier dans le flux.
+ `[GetRecords](https://docs.aws.amazon.com/amazondynamodb/latest/APIReference/API_streams_GetRecords.html)` – Renvoie les enregistrements de flux à partir d’une partition donnée. Vous devez fournir l’itérateur de partition renvoyé à partir d’une requête `GetShardIterator`.
Pour obtenir une description complète de ces opérations d’API, y compris des exemples de demandes et de réponses, consultez la [Référence des API Amazon DynamoDB Streams](https://docs.aws.amazon.com/amazondynamodb/latest/APIReference/API_Operations_Amazon_DynamoDB_Streams.html).
### Découverte de partitions
Découvrez de nouvelles partitions dans votre flux DynamoDB à l’aide de deux méthodes puissantes. En tant qu’utilisateur d’Amazon DynamoDB Streams, vous disposez de deux méthodes efficaces pour suivre et identifier de nouvelles partitions :
**Interrogation de l’ensemble de la topologie du flux**
Interrogez régulièrement le flux à l’aide de l’API `DescribeStream`. Celle-ci renvoie toutes les partitions du flux, y compris celles qui ont été créées. En comparant les résultats au fil du temps, vous pouvez détecter les partitions ajoutées récemment.
**Découverte de partitions enfants**
Recherchez un sous-ensemble de partitions à l’aide de l’API `DescribeStream` avec le paramètre `ShardFilter`. En spécifiant une partition parent dans la demande, DynamoDB Streams renvoie ses partitions enfants immédiates. Cette approche est utile lorsque vous avez uniquement besoin de suivre la lignée des partitions sans analyser l’intégralité du flux.
Les applications consommant des données de DynamoDB Streams peuvent passer efficacement de la lecture d’une partition fermée à sa partition enfant à l’aide du paramètre `ShardFilter`, évitant ainsi des appels répétés à l’API `DescribeStream` afin de récupérer et de parcourir la carte des partitions à la recherche des partitions fermées et ouvertes. Vous pouvez ainsi découvrir rapidement les partitions enfants après la fermeture d’une partition parent, ce qui rend vos applications de traitement de flux plus réactives et plus économiques.
Les deux méthodes vous permettent de suivre l’évolution de la structure de vos flux DynamoDB, afin de ne jamais manquer les mises à jour de données ou les modifications critiques de partitions.
### Limite de conservation des données pour DynamoDB Streams
Toutes les données dans DynamoDB Streams ont un time-to-live de 24 heures. Vous pouvez extraire et analyser les 24 dernières heures d’activité d’une table donnée. Cependant, les données datant de plus de 24 heures sont susceptibles d’être supprimées à tout moment.
Si vous désactivez un flux sur une table, les données du flux continueront d’être lisibles pendant 24 heures. Passé ce délai, les données expirent et les enregistrements de flux sont supprimés automatiquement. Il n’existe pas de mécanisme pour supprimer manuellement un flux existant. Vous devez attendre que la limite de rétention expire (24 heures) et tous les enregistrements de flux seront supprimés.
# DynamoDB Streams et time-to-live
Vous pouvez sauvegarder, ou traiter de toute autre façon, les éléments supprimés par [Time-to-live](TTL.md) (TTL) en activant Amazon DynamoDB Streams sur la table et en traitant les enregistrements de flux des éléments expirés. Pour en savoir plus, consultez [Lecture et traitement de flux](Streams.md#Streams.Processing).
L’enregistrement de flux contient un champ d’identité utilisateur `Records[].userIdentity`.
Les éléments supprimés par le processus Time-to-live après expiration ont les champs suivants :
+ `Records[].userIdentity.type`
`"Service"`
+ `Records[