Les traductions sont fournies par des outils de traduction automatique. En cas de conflit entre le contenu d'une traduction et celui de la version originale en anglais, la version anglaise prévaudra. # SerDe bibliothèques JSON Dans Athena, vous pouvez utiliser des SerDe bibliothèques pour désérialiser les données JSON. La désérialisation convertit les données JSON afin qu'elles puissent être sérialisées (écrites) dans un format différent comme Parquet ou ORC. + [Hive JSON SerDe](hive-json-serde.md) + [OpenX JSON SerDe](openx-json-serde.md) + [Amazon Ion Hive SerDe](ion-serde.md) **Note** Les bibliothèques Hive et OpenX s'attendent à ce que les données JSON soient sur une seule ligne (non formatées), les registres étant séparés par un caractère de nouvelle ligne. Amazon Ion étant un sur-ensemble de JSON, vous pouvez utiliser Amazon Ion Hive SerDe pour interroger des ensembles de données JSON autres qu'Amazon Ion. Contrairement aux bibliothèques SerDe JSON Hive et OpenX, Amazon SerDe Ion ne s'attend pas à ce que chaque ligne de données se trouve sur une seule ligne. Cette fonction est utile si vous souhaitez interroger des jeux de données JSON au format « pretty print » ou si vous souhaitez diviser les champs d'une ligne avec des caractères de saut de ligne. ## Noms des bibliothèques Utilisez l'une des options suivantes : [org.apache.hive.hcatalog.data. JsonSerDe](https://cwiki.apache.org/confluence/display/Hive/LanguageManual+DDL#LanguageManualDDL-JSON) [org.openx.data.json. JsonSerDe](https://github.com/rcongiu/Hive-JSON-Serde) [com.amazon.ionhiveserde. IonHiveSerDe](https://github.com/amzn/ion-hive-serde) # Hive JSON SerDe Le Hive JSON SerDe est couramment utilisé pour traiter des données JSON comme des événements. Ces événements sont représentés sous forme de chaînes sur une ligne de texte codées en JSON et séparées par une nouvelle ligne. Le JSON Hive n' SerDe autorise pas la duplication de clés `map` ou de noms de `struct` clés. **Note** Il SerDe s'attend à ce que chaque document JSON se trouve sur une seule ligne de texte sans aucun caractère de fin de ligne séparant les champs de l'enregistrement. Si le texte JSON est dans un joli format d'impression, vous pouvez recevoir un message d'erreur tel que HIVE\$1CURSOR\$1ERROR : Row is not a valid JSON Object ou HIVE\$1CURSOR\$1ERROR : : Unexpected JsonParseException end-of-input : expected close marker for OBJECT lorsque vous essayez d'interroger la table après l'avoir créée. Pour plus d'informations, consultez la section [Fichiers de données JSON](https://github.com/rcongiu/Hive-JSON-Serde#json-data-files) dans la SerDe documentation OpenX sur. GitHub L'exemple d'instruction DDL suivant utilise le code JSON Hive SerDe pour créer un tableau basé sur des exemples de données publicitaires en ligne. Dans la `LOCATION` clause, remplacez le *myregion* in `s3://amzn-s3-demo-bucket.elasticmapreduce/samples/hive-ads/tables/impressions` par l'identifiant de la région dans laquelle vous exécutez Athena (par exemple,`s3://us-west-2.elasticmapreduce/samples/hive-ads/tables/impressions`). ``` CREATE EXTERNAL TABLE impressions ( requestbegintime string, adid string, impressionid string, referrer string, useragent string, usercookie string, ip string, number string, processid string, browsercookie string, requestendtime string, timers struct < modellookup:string, requesttime:string >, threadid string, hostname string, sessionid string ) PARTITIONED BY (dt string) ROW FORMAT SERDE 'org.apache.hive.hcatalog.data.JsonSerDe' LOCATION 's3://amzn-s3-demo-bucket.elasticmapreduce/samples/hive-ads/tables/impressions'; ``` ## Spécifiez les formats d'horodatage avec le Hive JSON SerDe Pour analyser les valeurs de l'horodatage à partir d'une chaîne, vous pouvez ajouter le sous-champ `WITH SERDEPROPERTIES` à la clause `ROW FORMAT SERDE` et l'utiliser pour spécifier le paramètre `timestamp.formats`. Dans le paramètre, spécifiez une liste séparée par des virgules d'un ou plusieurs modèles d'horodatage, comme dans l'exemple suivant : ``` ... ROW FORMAT SERDE 'org.apache.hive.hcatalog.data.JsonSerDe' WITH SERDEPROPERTIES ("timestamp.formats"="yyyy-MM-dd'T'HH:mm:ss.SSS'Z',yyyy-MM-dd'T'HH:mm:ss") ... ``` Pour en savoir plus, consultez la rubrique [Horodatage](https://cwiki.apache.org/confluence/display/hive/languagemanual+types#LanguageManualTypes-TimestampstimestampTimestamps) dans la documentation Apache Hive. ## Chargement de la table pour interrogation Après avoir créé la table, exécutez [MSCK REPAIR TABLE](msck-repair-table.md) pour charger la table et la rendre interrogeable à partir d'Athena : ``` MSCK REPAIR TABLE impressions ``` ## CloudTrail Journaux de requêtes Vous pouvez utiliser le JSON Hive SerDe pour interroger les CloudTrail journaux. Pour plus d'informations et des exemples d'instructions `CREATE TABLE`, voir [AWS CloudTrail Journaux de requêtes](cloudtrail-logs.md). # OpenX JSON SerDe Comme le JSON Hive SerDe, vous pouvez utiliser le JSON OpenX pour traiter les données JSON. Les données sont également représentées sous forme de chaînes sur une ligne de texte codées en JSON et séparées par une nouvelle ligne. Comme le JSON Hive SerDe, le JSON OpenX SerDe n'autorise pas la duplication de clés `struct` ou de noms `map` de clés. ## Considérations et restrictions + Lorsque vous utilisez le JSON OpenX SerDe, le nombre de résultats et leurs valeurs peuvent être non déterministes. Les résultats peuvent contenir plus ou moins de lignes que prévu ou encore des valeurs nulles alors que les données sous-jacentes n’en contiennent pas. Pour contourner ce problème, utilisez le [Hive JSON SerDe](hive-json-serde.md) ou réécrivez les données dans un autre type de format de fichier. + Il SerDe s'attend à ce que chaque document JSON se trouve sur une seule ligne de texte sans aucun caractère de fin de ligne séparant les champs de l'enregistrement. Si le texte JSON est dans un joli format d'impression, vous pouvez recevoir un message d'erreur tel que HIVE\$1CURSOR\$1ERROR : Row is not a valid JSON Object ou HIVE\$1CURSOR\$1ERROR : : Unexpected JsonParseException end-of-input : expected close marker for OBJECT lorsque vous essayez d'interroger la table après l'avoir créée. Pour plus d'informations, consultez la section [Fichiers de données JSON](https://github.com/rcongiu/Hive-JSON-Serde#json-data-files) dans la SerDe documentation OpenX sur. GitHub ## Propriétés facultatives Contrairement au JSON Hive SerDe, le JSON OpenX SerDe possède également les propriétés SerDe facultatives suivantes qui peuvent être utiles pour corriger les incohérences dans les données. **use.null.for.invalid.data** Facultatif. La valeur par défaut est `FALSE`. Lorsque cette valeur est définie sur`TRUE`, les SerDe utilisations `NULL` des valeurs de colonne qui n'ont pas pu être désérialisées dans le type de colonne défini à partir du schéma de table. La définition de `use.null.for.invalid.data` sur `TRUE` peut entraîner des résultats incorrects ou inattendus, car les valeurs `NULL` remplacent les données non valides dans les colonnes présentant des problèmes de correspondance de schéma. Il est préférable de corriger les données dans vos fichiers ou votre schéma de table que d’activer cette propriété. Lorsque vous activez cette propriété, les données non valides n’entraînent pas l’échec des requêtes, ce qui peut vous empêcher de déceler des problèmes de qualité des données. **ignore.malformed.json** Facultatif. Lorsque la valeur est définie sur `TRUE`, cela vous permet d'ignorer la syntaxe JSON incorrecte. La valeur par défaut est `FALSE`. **dots.in.keys** Facultatif. La valeur par défaut est `FALSE`. Lorsqu'il est défini sur`TRUE`, permet de remplacer SerDe les points dans les noms des clés par des traits de soulignement. Par exemple, si le jeu de données JSON contient une clé portant le nom `"a.b"`, vous pouvez utiliser cette propriété pour définir le nom de la colonne comme étant `"a_b"` dans Athena. Par défaut (sans cela SerDe), Athena n'autorise pas les points dans les noms de colonnes. **case.insensitive** Facultatif. La valeur par défaut est `TRUE`. Lorsqu'il est défini sur`TRUE`, il SerDe convertit toutes les colonnes majuscules en minuscules. Pour utiliser des noms de clés sensibles à la casse dans vos données, utilisez `WITH SERDEPROPERTIES ("case.insensitive"= FALSE;)`. Ensuite, pour chaque clé qui n'est pas encore entièrement en minuscules, fournissez un mappage entre le nom de la colonne et le nom de la propriété à l'aide de la syntaxe suivante : ``` ROW FORMAT SERDE 'org.openx.data.jsonserde.JsonSerDe' WITH SERDEPROPERTIES ("case.insensitive" = "FALSE", "mapping.userid" = "userId") ``` Si vous avez deux clés, comme `URL` et `Url`, qui sont identiques quand elles sont écrites en minuscules, une erreur comme celle-ci peut se produire : HIVE\$1CURSOR\$1ERROR : La ligne n'est pas un objet JSON valide - JSONException : clé dupliquée « url » Pour résoudre ce problème, définissez la propriété `case.insensitive` sur `FALSE` et mapper les clés avec différents noms, comme dans l'exemple suivant : ``` ROW FORMAT SERDE 'org.openx.data.jsonserde.JsonSerDe' WITH SERDEPROPERTIES ("case.insensitive" = "FALSE", "mapping.url1" = "URL", "mapping.url2" = "Url") ``` **mappage** Facultatif. Cette propriété mappe les noms de colonnes aux clés JSON qui ne sont pas identiques aux noms de colonne. Le paramètre `mapping` est utile lorsque les données JSON contiennent des clés qui sont des [mots-clés](reserved-words.md). Par exemple, si vous avez une clé JSON nommée `timestamp`, utilisez la syntaxe suivante pour mapper la clé à une colonne nommée `ts`: ``` ROW FORMAT SERDE 'org.openx.data.jsonserde.JsonSerDe' WITH SERDEPROPERTIES ("mapping.ts" = "timestamp") ``` **Mapper les noms de champs imbriqués avec des deux-points à des noms compatibles avec Hive** Si vous avez un nom de champ avec des deux-points à l’intérieur d’un `struct`, vous pouvez utiliser la propriété `mapping` pour associer le champ à un nom compatible avec Hive. Par exemple, si vos définitions de type de colonne contiennent `my:struct:field:string`, vous pouvez mapper la définition à `my_struct_field:string` en incluant l’entrée suivante dans `WITH SERDEPROPERTIES` : ``` ("mapping.my_struct_field" = "my:struct:field") ``` L’exemple suivant montre l’instruction `CREATE TABLE` correspondante. ``` CREATE EXTERNAL TABLE colon_nested_field ( item struct) ROW FORMAT SERDE 'org.openx.data.jsonserde.JsonSerDe' WITH SERDEPROPERTIES ("mapping.my_struct_field" = "my:struct:field") ``` ## Exemple : données publicitaires L'exemple d'instruction DDL suivant utilise le code SerDe JSON OpenX pour créer un tableau basé sur les mêmes exemples de données publicitaires en ligne que ceux utilisés dans l'exemple du fichier JSON Hive. SerDe Dans la `LOCATION` clause, remplacez-le *myregion* par l'identifiant de la région dans laquelle vous exécutez Athena. ``` CREATE EXTERNAL TABLE impressions ( requestbegintime string, adid string, impressionId string, referrer string, useragent string, usercookie string, ip string, number string, processid string, browsercokie string, requestendtime string, timers struct< modellookup:string, requesttime:string>, threadid string, hostname string, sessionid string ) PARTITIONED BY (dt string) ROW FORMAT SERDE 'org.openx.data.jsonserde.JsonSerDe' LOCATION 's3://amzn-s3-demo-bucket.elasticmapreduce/samples/hive-ads/tables/impressions'; ``` ## Exemple : désérialisation des données JSON imbriquées Vous pouvez utiliser le JSON SerDes pour analyser des données plus complexes codées en JSON. Cela implique l'utilisation d'instructions `CREATE TABLE` utilisant des éléments `struct` et `array` pour représenter des structures imbriquées. L'exemple suivant crée une table Athena à partir de données JSON ayant des structures imbriquées. Il présente la structure suivante : ``` { "DocId": "AWS", "User": { "Id": 1234, "Username": "carlos_salazar", "Name": "Carlos", "ShippingAddress": { "Address1": "123 Main St.", "Address2": null, "City": "Anytown", "State": "CA" }, "Orders": [ { "ItemId": 6789, "OrderDate": "11/11/2022" }, { "ItemId": 4352, "OrderDate": "12/12/2022" } ] } } ``` N'oubliez pas qu'OpenX SerDe s'attend à ce que chaque enregistrement JSON se trouve sur une seule ligne de texte. Lorsqu’elles sont stockées dans Amazon S3, toutes les données de l’exemple précédent doivent figurer sur une seule ligne, comme illustré ci-dessous : ``` {"DocId":"AWS","User":{"Id":1234,"Username":"carlos_salazar","Name":"Carlos","ShippingAddress" ... ``` L'`CREATE TABLE`instruction suivante utilise le [Openx- JsonSerDe](https://github.com/rcongiu/Hive-JSON-Serde) avec les types de données de `array` collecte `struct` et pour établir des groupes d'objets pour les données d'exemple. ``` CREATE external TABLE complex_json ( docid string, `user` struct< id:INT, username:string, name:string, shippingaddress:struct< address1:string, address2:string, city:string, state:string >, orders:array< struct< itemid:INT, orderdate:string > > > ) ROW FORMAT SERDE 'org.openx.data.jsonserde.JsonSerDe' LOCATION 's3://amzn-s3-demo-bucket/myjsondata/'; ``` Utilisez une instruction `SELECT` semblable à la suivante pour interroger la table : ``` SELECT user.name as Name, user.shippingaddress.address1 as Address, user.shippingaddress.city as City, o.itemid as Item_ID, o.orderdate as Order_date FROM complex_json, UNNEST(user.orders) as temp_table (o) ``` Pour accéder aux champs de données des structures, la requête de l’exemple utilise la notation par points (par exemple, `user.name`). Vous pouvez utiliser la fonction `UNNEST` pour accéder aux données d’un tableau de structures (comme pour le champ `orders`). La fonction `UNNEST` aplatit le tableau en table temporaire (appelée `o` dans ce cas). Vous pouvez ainsi utiliser la notation par points comme vous le feriez avec les structures pour accéder aux éléments de tableau non imbriqués (par exemple, `o.itemid`). Le nom `temp_table`, utilisé dans l’exemple à des fins d’illustration, est souvent abrégé en `t`. Le tableau ci-dessous présente les résultats de la requête. **** | \$1 | Nom | Adresse | City | Item\$1ID | Order\$1date | | --- | --- | --- | --- | --- | --- | | 1 | Carlos | 123 Main St. | Anytown | 6789 | 11/11/2022 | | 2 | Carlos | 123 Main St. | Anytown | 4352 | 12/12/2022 | ## Ressources supplémentaires Pour de plus amples informations sur l'utilisation de JSON et de JSON imbriqué dans Athena, consultez les ressources suivantes : + [Créez des tables dans Amazon Athena à partir de JSON imbriqué et de mappages à l'aide JSONSer de De](https://aws.amazon.com/blogs/big-data/create-tables-in-amazon-athena-from-nested-json-and-mappings-using-jsonserde/) (AWS Big Data Blog) + [Je reçois des erreurs lorsque j'essaie de lire des données JSON dans Amazon Athena](https://aws.amazon.com/premiumsupport/knowledge-center/error-json-athena/) (article du AWS Knowledge Center) + [hive-json-schema](https://github.com/quux00/hive-json-schema)(GitHub) — Outil écrit en Java qui génère des `CREATE TABLE` instructions à partir d'exemples de documents JSON. Les instructions `CREATE TABLE` générées utilisent le SerDe JSON OpenX.