Construire un profil API personnalisé

Construisez un profil API personnalisé pour le connecteur API personnalisé DataSync. Ce guide couvre à la fois les scénarios de réponse API de base (plat) et avancés (imbriqués). L'exemple de base utilise des données de pays provenant de l'API REST Countries. Les exemples avancés utilisent des données d'Alphavantage.

Type	Description
Attributs de base (plat)	Les attributs sont accessibles directement à la racine de l'objet JSON (pas d'imbrication). Recommandé pour les réponses API simples comme les données REST Countries.
Données imbriquées avancées	Les attributs sont imbriqués dans des éléments, nécessitent la gestion d'éléments répétés variables ou incluent des tableaux/listes. Typique dans la finance, l'analyse ou des API plus complexes.

Profils API de base (attributs plats)

Démarrer un nouveau profil API

1. Ouvrez un éditeur de texte tel que Notepad.
2. Copiez et collez le XML de démarrage suivant dans votre nouveau document :

   <api:script xmlns:xs="http://www.w3.org/2001/XMLSchema" xmlns:api="http://apiscript.com/ns?v1" >
     <api:info xmlns:other="http://apiscript.com/ns?v1" title="Un Titre" desc="Une Description">

3. Remplacez les attributs title et desc par des valeurs pertinentes pour votre API.
   La valeur de title doit correspondre exactement au nom du fichier .rsd lorsque vous l'enregistrez—cela agit comme le nom de la table et l'identifiant unique pour l'extraction.

   Exemple :

   <api:info xmlns:other="http://apiscript.com/ns?v1" title="Pays" desc="Canada, France">

4. Enregistrez votre fichier avec une extension .rsd.

Récupérer et analyser les données de l'API

1. Visitez la documentation de l'API, par exemple, API REST Countries.
2. Copiez l'URL de l'endpoint (par exemple, https://restcountries.com/v3.1/all).
3. Dans Postman, créez une nouvelle requête GET et envoyez-la.
4. Examinez la réponse de l'API. Pour des APIs de base, les attributs sont à la racine de l'objet JSON.

Définir les attributs de table dans le profil API

1. Définissez les attributs sous la section <api:info ...> comme suit :

   <attr name="X" xs:type="X" readonly="true" other:xPath="X"/>

2. Remplacez chaque X par les valeurs appropriées.
3. Répétez la ligne <attr .../> pour tous les attributs que vous souhaitez dans votre tableau.

   Exemple :

   <attr name="name"         xs:type="string" readonly="true" other:xPath="name.common"/>
   <attr name="tld"          xs:type="string" readonly="true" other:xPath="tld"/>
   <attr name="status"       xs:type="string" readonly="true" other:xPath="status"/>
   <attr name="area"         xs:type="integer" readonly="true" other:xPath="area"/>
   <attr name="population"   xs:type="integer" readonly="true" other:xPath="population"/>
   ``

Directives de valeur d'attribut

Valeur	Description
attr name="X"	Nom de l'attribut, correspondant généralement au champ JSON associé dans l'API. Exemples de valeurs : name, capital, region
xs:type="X"	Type de données pour l'attribut dans l'API. Par exemple, utilisez string pour le texte et integer pour les nombres.
readonly="true"	(Optionnel) Indique que l'attribut est en lecture seule. Valeur par défaut pour tous les attributs.
other:xPath="X"	XPath ou chemin vers l'attribut dans l'API. Pour les attributs de niveau racine, utilisez leur nom ; pour les données imbriquées, spécifiez le chemin.
Propriété Spécifique	Ajoutez des attributs de propriété ici si nécessaire, comme key="true" pour désigner une clé primaire.

Définir les paramètres globaux et les méthodes de script

1. Définissez le type de contenu après vos attributs :

   <api:set attr="ContentType" value="application/json" />

2. Définissez la méthode de script et complétez le bloc de script :

   <api:script method="GET">
     <api:set attr="method" value="GET" />
     <api:set attr="uri" value="https://restcountries.com/v3.1/all" />
     <api:set attr="RepeatElement" value="/" />
     <api:call op="apisadoExecuteJSONGet">
       <api:push/>
     </api:call>
   </api:script>
   </api:script>

Compléter et utiliser le profil API

1. Enregistrez votre fichier .rsd.
2. Suivez Custom API Source Connector pour créer et configurer votre connexion DataSync.

Exemple

<api:script xmlns:xs="http://www.w3.org/2001/XMLSchema" xmlns:api="http://apiscript.com/ns?v1" >
  <api:info xmlns:other="http://apiscript.com/ns?v1" title="Pays" desc="Canada, France">
    <attr name="name"         xs:type="string" readonly="true" other:xPath="name.common"/>
    <attr name="tld"          xs:type="string" readonly="true" other:xPath="tld"/>
    <attr name="status"       xs:type="string" readonly="true" other:xPath="status"/>
    <attr name="area"         xs:type="integer" readonly="true" other:xPath="area"/>
    <attr name="population"   xs:type="integer" readonly="true" other:xPath="population"/>
  </api:info>
  <api:set attr="ContentType" value="application/json" />
  <api:script method="GET">
    <api:set attr="method" value="GET" />
    <api:set attr="uri" value="https://restcountries.com/v3.1/all" />
    <api:set attr="RepeatElement" value="/" />
    <api:call op="apisadoExecuteJSONGet">
      <api:push/>
    </api:call>
  </api:script>
</api:script>

Profils API avancés (attributs imbriqués et complexes)

Les profils API avancés sont utilisés lorsque les attributs sont imbriqués, lorsque les ensembles d'enregistrements (RepeatElements) ne sont pas à la racine, ou lors du travail avec des tableaux, des listes ou des clés variables.

Modèle	Description
Élément répété imbriqué	L'ensemble d'enregistrements est imbriqué sous un élément, pas à la racine (par exemple, "Taux de change de monnaie en temps réel").
Élément répété variable	L'ensemble d'enregistrements est sous un élément parent et ses clés enfants sont variables, comme des horodatages (par exemple, "Série temporelle FX (quotidienne)").
Tableaux et listes	Les attributs sont des tableaux ou des listes ; chaque élément de tableau est identifié par un index numérique (par exemple, "Features[0]").

Définir un profil API lorsque l'élément répété est imbriqué

1. Préparez votre fichier .rsd comme dans la configuration de base.
2. Dans la réponse de l'API, identifiez l'élément contenant vos enregistrements. (Par exemple : "Taux de change de monnaie en temps réel".)
3. Définissez la valeur RepeatElement au nom de l'ensemble d'enregistrements, dans ce format : /NomÉlément/. Par exemple : /Taux de change de monnaie en temps réel/.
4. Pour les attributs avec des caractères spéciaux, des espaces ou des accents, placez la valeur exacte entre crochets [ ] dans la section other:xPath.
5. Enregistrez votre fichier et suivez Custom API Source Connector pour créer et configurer votre connexion DataSync.

Exemple

Réponse API (dans Postman)

{
    "Taux de change de monnaie en temps réel": {
        "1. Code de devise d'origine": "USD",
        "2. Nom de la devise d'origine": "Dollar des États-Unis",
        "3. Code de devise cible": "JPY",
        "4. Nom de la devise cible": "Yen japonais",
        "5. Taux de change": "106.00200000",
        "6. Dernière mise à jour": "2020-07-24 13:17:15",
        "7. Fuseau horaire": "UTC",
        "8. Prix d'achat": "-",
        "9. Prix de vente": "-"
    }
}

Définition d'attribut (dans Notepad)

<other:xPath="[1. Code de devise d'origine]"/>
<other:xPath="[2. Nom de la devise d'origine]"/>
<other:xPath="[3. Code de devise cible]"/>
<other:xPath="[4. Nom de la devise cible]"/>
<other:xPath="[5. Taux de change]"/>
<other:xPath="[6. Dernière mise à jour]"/>
<other:xPath="[7. Fuseau horaire]"/>

Exemple de profil API complet

<api:script xmlns:xs="http://www.w3.org/2001/XMLSchema" xmlns:api="http://apiscript.com/ns?v1" >
    <!--Définit le nom de la table et la description et contient les définitions de colonne-->
    <api:info xmlns:other="http://apiscript.com/ns?v1" title="CurrencyUSD" desc="Devise USD">
      <attr name="Code de devise d'origine" xs:type="string"   readonly="true"  other:xPath="[1. Code de devise d'origine]"/>
      <attr name="Nom de la devise d'origine" xs:type="string"   readonly="true"  other:xPath="[2. Nom de la devise d'origine]"/>
      <attr name="Code de devise cible"   xs:type="string"   readonly="true"  other:xPath="[3. Code de devise cible]"/>
      <attr name="Nom de la devise cible"   xs:type="string"   readonly="true"  other:xPath="[4. Nom de la devise cible]"/>
      <attr name="Taux de change"      xs:type="decimal"  readonly="true"  other:xPath="[5. Taux de change]"/>
      <attr name="Dernière mise à jour"     xs:type="datetime" readonly="true"  other:xPath="[6. Dernière mise à jour]"/>
      <attr name="Fuseau horaire"          xs:type="string"   readonly="true"  other:xPath="[7. Fuseau horaire]"/>
    </api:info>
    <!--Définition des paramètres globaux-->
    <api:set attr="ContentType" value="application/json" />
    <api:script method="GET">
      <api:set attr="method" value="GET" />
      <api:set attr="uri" value="https://www.alphavantage.co/query?function=CURRENCY_EXCHANGE_RATE&from_currency=USD&to_currency=JPY&apikey=demo" />
      <api:set attr="RepeatElement" value="/Taux de change de monnaie en temps réel/" />
      <api:call op="apisadoExecuteJSONGet">
          <api:push/>
      </api:call>
    </api:script>
</api:script>

Définir un profil API lorsque l'élément répété est une variable

Utilisez cette méthode lorsque les enregistrements de données sont regroupés sous un élément parent, et que la clé de chaque groupe est variable (par exemple, des dates).

1. Préparez votre fichier .rsd comme dans la configuration de base.
2. Dans la réponse de l'API, localisez l'élément parent et identifiez les clés enfants variables (comme des dates). Par exemple : "Série temporelle FX (quotidienne)".
3. Définissez la valeur RepeatElement sur /ElémentParent/%/, où % représente la portion variable (par exemple : /Série temporelle FX (quotidienne)/%/).
4. Pour les attributs avec des caractères spéciaux, des espaces ou des accents, placez la valeur exacte entre crochets [ ] dans la section other:xPath.
5. Complétez, enregistrez et enregistrez votre profil.

Exemple

Réponse API (dans Postman)

{
    "Données Métas": {
        "1. Information": "Prix forex quotidiens (ouvert, haut, bas, fermant)",
        "2. Symbole d'origine": "CAD",
        "3. Symbole cible": "USD",
        "4. Taille de la sortie": "Compact",
        "5. Dernière mise à jour": "2020-07-28 11:25:00",
        "6. Fuseau horaire": "UTC"
    },
    "Série temporelle FX (quotidienne)": {
        "2020-07-28": {
            "1. ouvert": "0.7495",
            "2. haut": "0.7499",
            "3. bas": "0.7462",
            "4. fermant": "0.7465"
        },
        "2020-07-27": {
            "1. ouvert": "0.7447",
            "2. haut": "0.7493",
            "3. bas": "0.7440",
            "4. fermant": "0.7493"            
        },
        "2020-07-24": {
            "1. ouvert": "0.7461",
            "2. haut": "0.7473",
            "3. bas": "0.7433",
            "4. fermant": "0.7452"            
        },
    }
}

Définition d'attribut (dans Notepad)

<other:xPath="[1. ouvert]"/>
<other:xPath="[2. haut]"/>
<other:xPath="[3. bas]"/>
<other:xPath="[4. fermant]"/>

Exemple de profil API complet

<api:script xmlns:xs="http://www.w3.org/2001/XMLSchema" xmlns:api="http://apiscript.com/ns?v1" >
    <!--Définit le nom de la table et la description et contient les définitions de colonne-->
    <api:info xmlns:other="http://apiscript.com/ns?v1" title="Forex" desc="Pour récupérer des données Forex">
      <attr name="ouvert"   xs:type="decimal"   readonly="true"   other:xPath="[1. ouvert]"/>
      <attr name="haut"     xs:type="decimal"   readonly="true"   other:xPath="[2. haut]"/>
      <attr name="bas"      xs:type="decimal"   readonly="true"   other:xPath="[3. bas]"/>
      <attr name="fermant"  xs:type="decimal"   readonly="true"   other:xPath="[4. fermant]"/>
    </api:info>
    <!--Définition des paramètres globaux-->
    <api:set attr="ContentType" value="application/json" />
    <api:script method="GET">
      <api:set attr="method" value="GET" />
      <api:set attr="uri" value="https://www.alphavantage.co/query?function=FX_DAILY&from_symbol=CAD&to_symbol=USD&apikey=demo" />
      <api:set attr="RepeatElement" value="/Série temporelle FX (quotidienne)/%/" />
      <api:call op="apisadoExecuteJSONGet">
          <api:push/>
      </api:call>
    </api:script>
</api:script>

Définir des attributs pour des tableaux et des listes

Si vos données incluent des tableaux ou des listes (comme des adresses email ou des fonctionnalités), déclarez chaque élément de tableau en utilisant son index basé sur zéro entre crochets.

important

Pour les données de tableau ou de liste dans votre API, définissez chaque valeur par son index basé sur zéro, par exemple Features[0] et Features[1].

Exemple

Réponse API

{
    "NomUtilisateur" : "russellwhyte",
    "Prénom" : "Russell",
    "Nom" : "Whyte",
    "NomDeuxième" : null,
    "Genre" : "Masculin",
    "Âge" : null,
    "Emails" : ["Russell@example.com","Russell@contoso.com"],
    "FonctionnalitéPréférée" : "Fonctionnalité1",
    "Fonctionnalités" : ["Fonctionnalité1","Fonctionnalité2"],
    "InformationsAdresse" : [
        { 
            "Adresse" : "187 Suffolk Ln.",
            "Ville": {
                "Nom" : "Boise",
                "RégionPays" : "États-Unis",
                "Région" : "ID"
            }
        }
    ]
}

Définition du profil de l'API (dans Notepad)

<!--Définit le nom de la table et la description et contient les définitions de colonne-->
<api:info xmlns:other="http://apiscript.com/ns?v1" title="Personnes" desc="Obtenir toutes les personnes">
    <!--Définitions de colonne individuelles-->
    <attr name="NomUtilisateur"        xs:type="string"   readonly="true"   other:xPath="NomUtilisateur"/>
    <attr name="Prénom"                xs:type="string"   readonly="true"   other:xPath="Prénom"/>
    <attr name="Nom"                   xs:type="string"   readonly="true"   other:xPath="Nom"/>
    <attr name="NomDeuxième"           xs:type="string"   readonly="true"   other:xPath="NomDeuxième"/>
    <attr name="Genre"                 xs:type="decimal"  readonly="true"   other:xPath="Genre"/>
    <attr name="Âge"                   xs:type="datetime" readonly="true"   other:xPath="Âge"/>
    <attr name="Emails"                xs:type="string"   readonly="true"   other:xPath="Emails"/>
    <attr name="FonctionnalitéPréférée" xs:type="string"   readonly="true"   other:xPath="FonctionnalitéPréférée"/>
    <attr name="Fonctionnalité1"       xs:type="string"   readonly="true"   other:xPath="Fonctionnalités[0]"/>
    <attr name="Fonctionnalité2"       xs:type="string"   readonly="true"   other:xPath="Fonctionnalités[1]"/>
    <attr name="Adresse"               xs:type="string"   readonly="true"   other:xPath="InformationsAdresse/Adresse"/>
    <attr name="Ville"                 xs:type="string"   readonly="true"   other:xPath="InformationsAdresse/Ville/Nom"/>
    <attr name="RégionPays"            xs:type="string"   readonly="true"   other:xPath="InformationsAdresse/Ville/RégionPays"/>
    <attr name="Région"                xs:type="string"   readonly="true"   other:xPath="InformationsAdresse/Ville/Région"/>
</api:info>