DataWorks:Bonnes pratiques relatives à RestAPI Reader

Contexte

Pratique 1 : Lire des données depuis une API interrogeant une plage horaire

Scénario exemple : Définition de l'API

Préparation : Créer une table partitionnée MaxCompute

CREATE TABLE IF NOT EXISTS ods_xiaobo_rest2
(
  `axis`  STRING
  ,`value` BIGINT
  ,`createTime` STRING
)
PARTITIONED BY
(
  ds  STRING
)
LIFECYCLE 3650;

Configurer la tâche de synchronisation

1. Ajoutez une source de données RestAPI.

   Ajoutez une source de données RestAPI dans votre espace de travail DataWorks. Pour plus d'informations, consultez Ajouter une source de données RestAPI. Dans la boîte de dialogue Add RestAPI Data Source, spécifiez le Data Source Name et la Data Source Description, sélectionnez l'Applicable Environment (développement ou production), puis configurez le Default Request Header (valeur par défaut : {}). Les configurations clés sont les suivantes.

   • url : Définissez l'adresse de l'API RESTful.

   • Authentication Method : Choisissez une méthode d'authentification compatible avec l'API de votre source de données et renseignez les paramètres nécessaires.

   • Resource group connectivity : Les sources de données RestAPI ne prennent en charge que les groupes de ressources exclusifs pour Data Integration. Sélectionnez un groupe de ressources exclusif dédié à Data Integration et testez la connectivité entre la source de données et ce groupe.

2. Créez un nœud de synchronisation par lots et configurez la tâche.

   Créez un nœud de synchronisation par lots dans DataWorks Data Studio. Pour plus de détails, reportez-vous à Créer un nœud de synchronisation par lots. Voici les configurations principales.

   • Configurations de la Data Source :

     • Data Source : Sélectionnez la source de données RestAPI créée à l'étape précédente.

     • Request Method : L'API exemple étant de type GET, sélectionnez GET.

     • Return Data Structure : La réponse de l'API exemple est un tableau JSON. Choisissez Array Data.

     • The JSON path for data storage : Les données retournées par l'API exemple se trouvent sous le champ data. Indiquez data.

     • Request Param : Combinez les paramètres de requête avec des paramètres de planification afin de synchroniser quotidiennement les données de la journée en cours.

       • Définissez les paramètres de requête sur startTime=${extract_day} ${start_time}&endTime=${extract_day} ${end_time}

       • Dans les paramètres de planification, ajoutez trois variables : extract_day=${yyyy-mm-dd}, start_time=00:00:00 et end_time=23:59:59.

       Si la date d'exécution est le 2023-01-05, la valeur de extract_day sera 2023-01-04, et les paramètres de requête seront concaténés ainsi : startTime=2023-01-04 00:00:00&endTime=2023-01-04 23:59:59.

   • Configurations de la Data Destination :

     • Data Source et Table : Sélectionnez la table partitionnée MaxCompute créée précédemment.

     • Partition Information : Associez les informations de partition aux paramètres de planification.

       • Définissez l'information de partition sur ${bizdate}.

       • Dans les paramètres de planification, ajoutez une variable : bizdate=$bizdate.

       Si la date d'exécution est le 2023-01-05, la valeur de l'information de partition sera 20230104.

   • Configurations du Field Mapping : Conformément à la définition des données de l'API, saisissez les noms de colonnes issus de la réponse RestAPI. Ces noms respectent la casse. Une fois les colonnes ajoutées, utilisez The same name mapping ou tracez manuellement des lignes pour établir les correspondances.

Exécution de test

Vérification des données

select * from ods_xiaobo_rest2 where ds='20230104' order by createtime;

Soumettre, déployer et recharger les données

Pratique 2 : Lire des données depuis une API RestAPI paginée

Scénario exemple : Définition de l'API

Préparation : Créer une table partitionnée MaxCompute

CREATE TABLE IF NOT EXISTS ods_xiaobo_rest1
(
  `id` BIGINT
  ,`name` STRING
)
PARTITIONED BY
(
  ds  STRING
)
LIFECYCLE 3650;

Configurer la tâche de synchronisation

1. Ajoutez une source de données RestAPI.

   Ajoutez une source de données RestAPI dans votre espace de travail DataWorks. Pour plus d'informations, consultez Ajouter une source de données RestAPI. Dans la boîte de dialogue Add RestAPI Data Source, spécifiez le Data Source Name et la Data Source Description, sélectionnez l'Applicable Environment (développement ou production), puis configurez le Default Request Header (valeur par défaut : {}). Les configurations clés sont les suivantes.

   • url : Définissez l'adresse de l'API RESTful.

   • Authentication Method : Choisissez une méthode d'authentification compatible avec l'API de votre source de données et renseignez les paramètres nécessaires.

   • Resource group connectivity : Les sources de données RestAPI ne prennent en charge que les groupes de ressources exclusifs pour Data Integration. Sélectionnez un groupe de ressources exclusif dédié à Data Integration et testez la connectivité entre la source de données et ce groupe.

2. Créez un nœud de synchronisation par lots et configurez la tâche.

   Créez un nœud de synchronisation par lots dans DataWorks Data Studio. Pour plus de détails, reportez-vous à Créer un nœud de synchronisation par lots. Voici les configurations principales.

   • Configurations de la Data Source :

     • Data Source : Sélectionnez la source de données RestAPI créée à l'étape précédente.

     • Request Method : L'API exemple étant de type GET, sélectionnez GET.

     • Return Data Structure : La réponse de l'API exemple est un tableau JSON. Choisissez Array Data.

     • The JSON path for data storage : Les données retournées par l'API exemple se trouvent sous le champ data. Indiquez data.

     • Request Param : La taille de page est fixe. Définissez-la sur pageSize=50. Il est recommandé de ne pas définir une taille de page trop importante, car cela pourrait exercer une pression excessive sur le serveur RestAPI et sur la tâche de synchronisation.

     • The number of requests : Sélectionnez Multiple Requests pour cet exemple.

       Le paramètre de pagination pour cette API est pageNum. Après avoir sélectionné Multiple Requests, configurez les paramètres associés comme suit :

       • Parameter used for multiple requests : Définissez cette valeur sur pageNum.

       • StartIndex : Définissez cette valeur sur 1.

       • Step : Définissez cette valeur sur 1.

       • EndIndex : Définissez cette valeur sur 100.

   • Configurations de la Data Destination :

     • Data Source et Table : Sélectionnez la table partitionnée MaxCompute créée précédemment.

     • Partition Information : Associez les informations de partition aux paramètres de planification.

       • Définissez l'information de partition sur ${bizdate}.

       • Dans les paramètres de planification, ajoutez une variable : bizdate=$bizdate.

       Si la date d'exécution est le 2023-01-05, la valeur de l'information de partition sera 20230104.

   • Configurations du Field Mapping : Conformément à la définition des données de l'API, saisissez les noms de colonnes issus de la réponse RestAPI. Ces noms respectent la casse. Une fois les colonnes ajoutées, utilisez The same name mapping ou tracez manuellement des lignes pour établir les correspondances.

Exécution de test

Vérification des données

select * from ods_xiaobo_rest1 where ds='20230104' order by id;

Pratique 3 : Lire des données depuis une API RestAPI de type POST

Scénario exemple : Définition de l'API

Préparation : Créer une table partitionnée MaxCompute

CREATE TABLE IF NOT EXISTS ods_xiaobo_rest3
(
  `user_id` BIGINT
  ,`name` STRING
  ,`axis`  STRING
  ,`value` BIGINT
  ,`create_time` STRING
)
PARTITIONED BY
(
  ds  STRING
)
LIFECYCLE 3650;

Configurer la tâche de synchronisation

1. Ajoutez une source de données RestAPI.

   Ajoutez une source de données RestAPI dans votre espace de travail DataWorks. Pour plus d'informations, consultez Ajouter une source de données RestAPI. Dans la boîte de dialogue Add RestAPI Data Source, spécifiez le Data Source Name et la Data Source Description, sélectionnez l'Applicable Environment (développement ou production), puis configurez le Default Request Header (valeur par défaut : {}). Les configurations clés sont les suivantes.

   • url : Définissez l'adresse de l'API RESTful.

   • Authentication Method : Choisissez une méthode d'authentification compatible avec l'API de votre source de données et renseignez les paramètres nécessaires.

   • Resource group connectivity : Les sources de données RestAPI ne prennent en charge que les groupes de ressources exclusifs pour Data Integration. Sélectionnez un groupe de ressources exclusif dédié à Data Integration et testez la connectivité entre la source de données et ce groupe.

2. Créez un nœud de synchronisation par lots et configurez la tâche.

   Créez un nœud de synchronisation par lots dans DataWorks Data Studio. Pour plus de détails, reportez-vous à Créer un nœud de synchronisation par lots. Voici les configurations principales.

   • Configurations de la Data Source :

     • Data Source : Sélectionnez la source de données RestAPI créée à l'étape précédente.

     • Request Method : L'API exemple étant de type POST, sélectionnez POST.

     • Return Data Structure : La réponse de l'API exemple est un tableau JSON. Choisissez Array Data.

     • The JSON path for data storage : Les données retournées par l'API exemple se trouvent sous le champ data. Indiquez data.

     • Header : L'API POST de cet exemple accepte un corps de requête JSON. Définissez cette valeur sur {"Content-Type":"application/json"}.

     • Request Param : Combinez les paramètres de requête avec des paramètres de planification afin de synchroniser quotidiennement les données de la journée en cours.

       • Définissez les paramètres de requête sur

         {
         
             "userId":16,
         
             "startTime":"${extract_day} 00:00:00",
         
             "endTime":"${extract_day} 23:59:59"
         
         }

       • Dans les paramètres de planification, ajoutez une variable : extract_day=${yyyy-mm-dd}.

   • Configurations de la Data Destination :

     • Data Source et Table : Sélectionnez la table partitionnée MaxCompute créée précédemment.

     • Partition Information : Associez les informations de partition aux paramètres de planification.

       • Définissez l'information de partition sur ${bizdate}.

       • Dans les paramètres de planification, ajoutez une variable : bizdate=$bizdate.

       Si la date d'exécution est le 2023-01-05, la valeur de l'information de partition sera 20230104.

   • Configurations du Field Mapping : Conformément à la définition des données de l'API, saisissez les noms de colonnes issus de la réponse RestAPI. Vous pouvez utiliser des points (.) pour séparer les colonnes imbriquées. Ces noms respectent la casse. Une fois les colonnes ajoutées, utilisez The same name mapping ou tracez manuellement des lignes pour établir les correspondances.

Exécution de test

Vérification des données

select * from ods_xiaobo_rest3 where ds='20230105' order by create_time;

Pratique 4 : Itérer sur un paramètre de requête pour lire depuis une API RestAPI

Scénario exemple : Définition de l'API

Dans cet exercice, vous lisez itérativement des données depuis une API RESTful pour les écrire dans une table partitionnée MaxCompute. L'API RESTful utilisée est une API GET de test auto-générée qui retourne des données météorologiques en fonction des paramètres d'entrée date, province et city.

Lors de vos opérations réelles, adaptez les configurations à l'API que vous utilisez. L'API présentée ici sert uniquement d'exemple pour illustrer le flux de travail.

• Exemple de requête :

  http://TestAPIAddress:Port/rest/test5?date=2023-01-04&province=zhejiang&city=hangzhou

• Exemple de réponse :

  {
    "province": "P1",
    "city": "hz",
    "date": "2023-01-04",
    "minTemperature": "-14",
    "maxTemperature": "-7",
    "unit": "℃",
    "weather": "cool"
  }

• Exemple d'appel API dans un outil de test : Envoyez une requête GET via un outil tel que Postman. Passez les paramètres date=2023-01-04, province=p1 et city=hz. L'API renvoie une réponse JSON contenant les informations minTemperature (-14), maxTemperature (-7), unit (℃) et weather (COOL) correspondantes.

Préparation : Créer une table de paramètres et une table partitionnée MaxCompute

Dans cette pratique, les données lues depuis l'API sont synchronisées vers une table partitionnée MaxCompute. Vous devez d'abord créer une table de paramètres pour stocker les valeurs de province et city destinées à l'itération, puis créer une table partitionnée pour accueillir les données synchronisées.

L'utilisation d'une table partitionnée avec la commande overwrite permet d'écraser la partition concernée. Ainsi, la tâche de synchronisation peut être relancée sans duplication des données, ce qui facilite également l'analyse ultérieure.

Voici les instructions CREATE TABLE correspondantes :

CREATE TABLE IF NOT EXISTS `citys`
(
  `province` STRING ,
  `city` STRING
);

insert into citys
select 'shanghai','shanghai'
union all select 'zhejiang','hangzhou'
union all select 'sichuan','chengdu';

CREATE TABLE IF NOT EXISTS ods_xiaobo_rest5
(
    `minTemperature` STRING ,
    `maxTemperature` STRING ,
    `unit` STRING ,
    `weather` STRING 
)
PARTITIONED BY 
(
    `province` STRING ,
    `city` STRING ,
    `ds`  STRING
)
LIFECYCLE 3650;

Si vous utilisez DataWorks Standard Edition et soumettez les tables créées à l'environnement de production, celles-ci seront visibles dans Data Map.

Configurer la tâche de synchronisation

1. Ajoutez une source de données RestAPI.

   Ajoutez une source de données RestAPI dans votre espace de travail DataWorks. Pour plus d'informations, consultez Ajouter une source de données RestAPI. Dans la boîte de dialogue Add RestAPI Data Source, spécifiez le Data Source Name et la Data Source Description, sélectionnez l'Applicable Environment (développement ou production), puis configurez le Default Request Header (valeur par défaut : {}). Les configurations clés sont les suivantes :

   • url : Définissez l'adresse de l'API RESTful.

   • Authentication Method : Choisissez une méthode d'authentification compatible avec l'API de votre source de données et renseignez les paramètres nécessaires.

   • Resource group connectivity : Sélectionnez le groupe de ressources spécifié et testez la connectivité.

2. Créez un nœud d'affectation nommé setval_citys dans DataStudio. Pour plus d'informations, consultez Créer un nœud d'affectation.

   Les configurations clés sont les suivantes :

   N°	Description
   ①	Langage d'affectation : ODPS SQL Code d'affectation : SELECT province ,city FROM citys;
   ②	Propriété de réexécution : Définissez cette option sur You can run again after successful or failed operation..

   Une fois la configuration terminée, soumettez et déployez le nœud d'affectation.

3. Créez un nœud for-each dans DataStudio. Pour plus d'informations, consultez Créer un nœud for-each. Les configurations clés sont les suivantes :

   N°	Description
   ①	Propriété de réexécution : Définissez cette option sur You can run again after successful or failed operation..
   ②	Dépendance du nœud en amont : Sélectionnez le nœud de l'étape précédente, à savoir le nœud setval_citys.
   ③	Paramètre de contexte du nœud : Sélectionnez la source du paramètre d'entrée.
   ④	Nœud de synchronisation par lots : Configurez le nœud de synchronisation par lots à l'intérieur du nœud for-each. Pour plus de détails, voir les étapes suivantes.

4. Créez un nœud de synchronisation par lots et configurez la tâche. Pour plus d'informations, consultez Créer un nœud de synchronisation par lots.

   Les configurations clés sont les suivantes :

   N°	Description
   ①	Configurez les paramètres de planification comme suit : bizdate=$[yyyymmdd-1] bizdate_year=$[yyyy-1] bizdate_month=$[mm-1] bizdate_day=$[dd-1]
   ②	Configurez les paramètres de requête RestAPI. Les paramètres province et city proviennent du nœud for-each. date=${bizdate_year}-${bizdate_month}-${bizdate_day}&province=${dag.foreach.current[0]}&city=${dag.foreach.current[1]}
   ③	Configurez le paramètre de partition MaxCompute. Le paramètre province provient du nœud for-each. province=${dag.foreach.current[0]}
   ④	Configurez le paramètre de partition MaxCompute. Le paramètre city provient du nœud for-each. city=${dag.foreach.current[1]}
   ⑤	Configurez le paramètre de partition MaxCompute. Le paramètre ds provient des paramètres de planification. ds=${bizdate}
   ⑥	Conformément à la définition des données de l'API, saisissez les noms de colonnes issus de la réponse RestAPI. Ces noms respectent la casse. Une fois les colonnes ajoutées, utilisez The same name mapping ou tracez manuellement des lignes pour établir les correspondances.

   Une fois la configuration terminée, soumettez et déployez le nœud for-each.

Exécution de test

1. Après avoir soumis et déployé avec succès le nœud d'affectation et le nœud for-each, accédez aux tâches planifiées dans Operation Center et effectuez une opération de backfill sur le nœud d'affectation. Pour plus d'informations, consultez Backfill data.

2. Sélectionnez la date métier pour la tâche de backfill et les nœuds en aval en fonction de votre scénario réel.

3. Après l'exécution de la tâche, vérifiez les paramètres d'exécution dans les détails de l'instance de backfill pour vous assurer qu'ils correspondent à vos attentes, et consultez le journal d'exécution pour en valider l'exactitude.

   Dans cet exemple, les données sont écrites dans la partition province=shanghai,city=shanghai,ds=20231215 de la table MaxCompute.

Vérification des données

Exécutez une requête ad hoc dans Data Studio afin de vérifier si les données ont été correctement synchronisées vers MaxCompute. Voici un exemple de requête :

Dans cet exemple, ods_xiaobo_rest5 est la table partitionnée MaxCompute créée lors de l'étape de Préparation.

SELECT  weather
        ,mintemperature
        ,maxtemperature
        ,unit
        ,province
        ,city
        ,ds
FROM    ods_xiaobo_rest5
WHERE   ds != 1
ORDER BY ds,province,city;

Une fois la requête terminée, vérifiez si les données ont été correctement synchronisées vers MaxCompute.