Référence de mise en place d’intégration externe

Les objets de base de données suivants sont créés par le biais du fichier setup_external_integration.sql.

PUBLIC.SETUP_EXTERNAL_INTEGRATION_WITH_NAMES()

La procédure modifie d’autres procédures ou fonctions, dont les signatures sont transmises en tant qu’argument de la procédure dans un tableau, avec une EXTERNAL ACCESS INTEGRATION et des noms d’objets SECRET qui sont stockés dans la configuration de la connexion sous les clés suivantes :

  • external_access_configuration pour un identificateur d’objet EXTERNAL ACCESS INTEGRATION.

  • secret pour un identificateur d’objet SECRET.

Le secret est attaché à la procédure/fonction modifiée avec la clé credentials. Par défaut, la procédure n’est disponible pour aucun des rôles utilisateurs de l’application.

Signature de la procédure

CREATE OR REPLACE PROCEDURE PUBLIC.SETUP_EXTERNAL_INTEGRATION_WITH_NAMES(methods ARRAY)
    RETURNS VARIANT
    LANGUAGE SQL
    [...]

Où :

  • methods ARRAY représente un tableau de signatures de procédures/fonctions sous forme de variables, par exemple ARRAY_CONSTRUCT('PUBLIC.PROC_1(VARIANT)', 'PUBLIC.PROC_2()').

Valeurs de retour

La procédure renvoie toujours une variante avec une structure de réponse de connecteur standard.

En cas d’exécution réussie de la procédure :

{
  "response_code": "OK",
  "message": "Successfully set up <number> method(s)."
}

Note

L’exécution de la procédure se termine avec succès même si les signatures de procédures/fonctions transmises en tant qu’arguments ne représentent pas des objets existants ou si une application n’a pas accès à ces objets. Le processus de modification de ce type de procédure/fonction est ignoré et la procédure générale se poursuit.

En cas de défaillance :

{
  "response_code": "<ERROR_CODE>",
  "message": "<error message>",
  "SQLCODE": "<code of a thrown exception>",
  "SQLERRM": "<error message of a thrown exception>",
  "SQLCODE": "<sql code of a thrown exception>"
}

Attention

La procédure ne génère pas d’erreur si une erreur survient au cours de l’exécution. Chaque erreur est intégrée dans la réponse du connecteur et mappée sur le site response_code, ce qui permet de valider le résultat de la procédure et de l’utiliser en toute sécurité sur le site setup.sql pendant l’installation de l’application (sinon, toute erreur non gérée pourrait interrompre et mettre fin au processus d’installation de l’application).

Erreurs possibles

  • EAI_UNAVAILABLE - un objet EXTERNAL ACCESS INTEGRATION n’existe pas ou une application ne dispose pas d’un privilège USAGE sur cet objet.

  • SECRET_UNAVAILABLE - un objet SECRET n’existe pas ou une application n’a pas au moins un privilège READ sur cet objet.

  • INTERNAL ERROR - ce code de réponse est renvoyé en cas d’erreurs inattendues.

Exemple d’utilisation

CALL PUBLIC.SETUP_EXTERNAL_INTEGRATION_WITH_NAMES(ARRAY_CONSTRUCT(
    'PUBLIC.TEST_CONNECTION()',
    'PUBLIC.FINALIZE_CONFIGURATION(VARIANT)',
    'PUBLIC.TEMPLATE_WORKER(NUMBER, STRING)')
);

PUBLIC.SETUP_EXTERNAL_INTEGRATION_WITH_REFERENCES()

La procédure modifie d’autres procédures ou fonctions, dont les signatures sont transmises en tant qu’argument de procédure dans un tableau, avec un objet EXTERNAL ACCESS INTEGRATION et un objet SECRET qui sont affectés aux références de l’application. Lorsque vous utilisez cette procédure, il est exigé que les références soient enregistrées sous les noms suivants :

  • EAI_REFERENCE - pour obtenir une référence à un objet EXTERNAL ACCESS INTEGRATION.

  • SECRET_REFERENCE - pour obtenir une référence à un objet SECRET.

Le secret est attaché à la procédure/fonction modifiée avec la clé credentials. Par défaut, la procédure n’est disponible pour aucun des rôles utilisateurs de l’application.

Signature de la procédure

CREATE OR REPLACE PROCEDURE PUBLIC.SETUP_EXTERNAL_INTEGRATION_WITH_REFERENCES(methods ARRAY)
    RETURNS VARIANT
    LANGUAGE SQL
    [...]

Où :

  • methods ARRAY représente un tableau de signatures de procédures/fonctions sous forme de variables, par exemple ARRAY_CONSTRUCT('PUBLIC.PROC_1(VARIANT)', 'PUBLIC.PROC_2()').

Valeurs de retour

La procédure renvoie toujours une variante avec une structure de réponse de connecteur standard.

En cas d’exécution réussie de la procédure :

{
  "response_code": "OK",
  "message": "Successfully set up <number> method(s)."
}

Note

L’exécution de la procédure se termine avec succès même si les signatures de procédures/fonctions transmises en tant qu’arguments ne représentent pas des objets existants ou si une application n’a pas accès à ces objets. Le processus de modification de ce type de procédure/fonction est ignoré et la procédure générale se poursuit.

En cas de défaillance :

{
  "response_code": "<ERROR_CODE>",
  "message": "<error message>",
  "SQLCODE": "<code of a thrown exception>",
  "SQLERRM": "<error message of a thrown exception>",
  "SQLCODE": "<sql code of a thrown exception>"
}

Attention

La procédure ne génère pas d’erreur si une erreur survient au cours de l’exécution. Chaque erreur est intégrée dans la réponse du connecteur et mappée sur le site response_code, ce qui permet de valider le résultat de la procédure et de l’utiliser en toute sécurité sur le site setup.sql pendant l’installation de l’application (sinon, toute erreur non gérée pourrait interrompre et mettre fin au processus d’installation de l’application).

Erreurs possibles

  • EAI_UNAVAILABLE - un objet EXTERNAL ACCESS INTEGRATION n’existe pas ou une application ne dispose pas d’un privilège USAGE sur cet objet.

  • SECRET_UNAVAILABLE - un objet SECRET n’existe pas ou une application n’a pas au moins un privilège READ sur cet objet.

  • INTERNAL ERROR - ce code de réponse est renvoyé en cas d’erreurs inattendues.

Exemple d’utilisation

CALL PUBLIC.SETUP_EXTERNAL_INTEGRATION_WITH_REFERENCES(ARRAY_CONSTRUCT(
    'PUBLIC.TEST_CONNECTION()',
    'PUBLIC.FINALIZE_CONFIGURATION(VARIANT)',
    'PUBLIC.TEMPLATE_WORKER(NUMBER, STRING)')
);

PUBLIC.SETUP_EXTERNAL_INTEGRATION()

Il s’agit d’une version brute des procédures décrites ci-dessus qui est également utilisée par eux. La procédure modifie d’autres procédures ou fonctions, dont les signatures sont transmises en tant qu’argument de procédure dans un tableau, avec un EXTERNAL ACCESS INTEGRATION et des noms d’objets SECRET qui sont également transmis en tant qu’arguments de procédure. Cette procédure laisse au fournisseur la liberté de décider comment fournir à la procédure des informations sur les objets liés à l’accès externe.

Le secret est attaché à la procédure/fonction modifiée avec la clé credentials. Par défaut, la procédure n’est disponible pour aucun des rôles utilisateurs de l’application.

L’utilisation de cette procédure n’est recommandée que lorsqu’il n’est pas possible d’utiliser les procédures décrites ci-dessus, qui utilisent des références avec des noms prédéfinis ou des noms d’objets stockés sous des clés prédéfinies dans la configuration de la connexion.

Signature de la procédure

CREATE OR REPLACE PROCEDURE PUBLIC.SETUP_EXTERNAL_INTEGRATION(eai_idf VARCHAR, secret_idf VARCHAR, methods ARRAY)
    RETURNS VARIANT
    LANGUAGE SQL
    [...]

Où :

  • eai_idf VARCHAR - représente l’identificateur d’un objet EXTERNAL_ACCESS_INTEGRATION. Si vous voulez y passer un nom de référence, vous devez l’envelopper comme suit : 'reference(\'<reference_name>\')'

  • secret_idf VARCHAR - représente l’identificateur d’un objet SECRET. Si vous voulez y passer un nom de référence, vous devez l’envelopper comme suit : 'reference(\'<reference_name>\')'

  • methods ARRAY représente un tableau de signatures de procédures/fonctions sous forme de variables, par exemple ARRAY_CONSTRUCT('PUBLIC.PROC_1(VARIANT)', 'PUBLIC.PROC_2()').

Valeurs de retour

La procédure renvoie toujours une variante avec une structure de réponse de connecteur standard.

En cas d’exécution réussie de la procédure :

{
  "response_code": "OK",
  "message": "Successfully set up <number> method(s)."
}

Note

L’exécution de la procédure se termine avec succès même si les signatures de procédures/fonctions transmises en tant qu’arguments ne représentent pas des objets existants ou si une application n’a pas accès à ces objets. Le processus de modification de ce type de procédure/fonction est ignoré et la procédure générale se poursuit.

En cas de défaillance :

{
  "response_code": "<ERROR_CODE>",
  "message": "<error message>",
  "SQLCODE": "<code of a thrown exception>",
  "SQLERRM": "<error message of a thrown exception>",
  "SQLCODE": "<sql code of a thrown exception>"
}

Attention

La procédure ne génère pas d’erreur si une erreur survient au cours de l’exécution. Chaque erreur est intégrée dans la réponse du connecteur et mappée sur le site response_code, ce qui permet de valider le résultat de la procédure et de l’utiliser en toute sécurité sur le site setup.sql pendant l’installation de l’application (sinon, toute erreur non gérée pourrait interrompre et mettre fin au processus d’installation de l’application).

Erreurs possibles

  • EAI_UNAVAILABLE - un objet EXTERNAL ACCESS INTEGRATION n’existe pas ou une application ne dispose pas d’un privilège USAGE sur cet objet.

  • SECRET_UNAVAILABLE - un objet SECRET n’existe pas ou une application n’a pas au moins un privilège READ sur cet objet.

  • INTERNAL ERROR - ce code de réponse est renvoyé en cas d’erreurs inattendues.

Exemple d’utilisation

CALL PUBLIC.SETUP_EXTERNAL_INTEGRATION(
    'EXAMPLE_EAI_IDF',
    'reference(\'CUSTOM_REFERENCE_NAME\')',
    ARRAY_CONSTRUCT('PUBLIC.TEST_CONNECTION()',
    'PUBLIC.FINALIZE_CONFIGURATION(VARIANT)',
    'PUBLIC.TEMPLATE_WORKER(NUMBER, STRING)')
);

Lorsque vous souhaitez utiliser cette procédure dans le script setup.sql et que les noms des objets SECRET et EXTERNAL ACCESS INTEGRATION sont stockés d’une manière différente de celle recommandée par Native SDK for Connectors, vous devez récupérer ces valeurs d’une manière ou d’une autre. Dans ce cas, vous pouvez utiliser le mécanisme EXECUTE IMMEDIATE :

EXECUTE IMMEDIATE $$
    DECLARE
        eai_idf VARCHAR;
        secret_idf VARCHAR;
    BEGIN
        -- retrieve name of an EXTERNAL ACCESS INTEGRATION object
        :eai_idf = <eai_object_name>;

        -- retrieve name of a SECRET object
        :secret_idf = <secret_object_name>;

        CALL PUBLIC.SETUP_EXTERNAL_INTEGRATION(
            :eai_idf,
            :secret_idf,
            ARRAY_CONSTRUCT('PUBLIC.TEST_CONNECTION()',
            'PUBLIC.FINALIZE_CONFIGURATION(VARIANT)',
            'PUBLIC.TEMPLATE_WORKER(NUMBER, STRING)')
        );
    END;
$$
;