Referência de configuração de integração externa¶

Os seguintes objetos de banco de dados são criados por meio do arquivo setup_external_integration.sql.

PUBLIC.SETUP_EXTERNAL_INTEGRATION_WITH_NAMES()¶

O procedimento altera outros procedimentos ou funções, cujas assinaturas são passadas como argumento do procedimento em uma matriz, com um EXTERNAL ACCESS INTEGRATION e um nome de objeto SECRET que são armazenados na configuração da conexão sob as seguintes chaves:

external_access_configuration para um identificador de objeto EXTERNAL ACCESS INTEGRATION.

secret para um identificador de objeto SECRET.

O segredo é anexado ao procedimento/função alterado com a chave credentials. Por padrão, o procedimento não está disponível para nenhuma das funções de usuário do aplicativo.

Assinatura do procedimento¶

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

Copy

Onde:

methods ARRAY representam uma matriz de assinaturas de procedimentos/funções como varchar, por exemplo, ARRAY_CONSTRUCT('PUBLIC.PROC_1(VARIANT)', 'PUBLIC.PROC_2()').

Valores retornados¶

O procedimento sempre retorna uma variante com uma estrutura de resposta de conector padrão.

No caso de uma execução bem-sucedida do procedimento:

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

A execução do procedimento é concluída com êxito mesmo quando as assinaturas de procedimento/função passadas como argumentos não representam objetos existentes ou quando um aplicativo não tem acesso a esses objetos. O processo de alteração desse tipo de procedimento/função é ignorado e o processo geral continua.

Em caso de falha:

{
  "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>"
}
Copy
Atenção

O procedimento não gera nenhum erro se ocorrer um erro durante a execução. Cada erro é incluído na resposta do conector e mapeado para o response_code apropriado, o que permite validar o resultado do procedimento e usá-lo com segurança no setup.sql durante a instalação do aplicativo (caso contrário, qualquer erro não tratado poderia interromper e encerrar o processo de instalação do aplicativo).

Possíveis erros¶

EAI_UNAVAILABLE - um objeto EXTERNAL ACCESS INTEGRATION não existe ou um aplicativo não tem o privilégio USAGE nele.
SECRET_UNAVAILABLE - um objeto SECRET não existe ou um aplicativo não tem pelo menos um privilégio READ nele.
INTERNAL ERROR - esse código de resposta é retornado em caso de ocorrências de erros inesperados.

Exemplo de uso¶

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

Copy

PUBLIC.SETUP_EXTERNAL_INTEGRATION_WITH_REFERENCES()¶

O procedimento altera outros procedimentos ou funções, cujas assinaturas são passadas como argumento do procedimento em uma matriz, com objetos EXTERNAL ACCESS INTEGRATION e SECRET que são atribuídos às referências do aplicativo. Ao usar esse procedimento, é necessário ter referências registradas com os seguintes nomes:

EAI_REFERENCE - para uma referência a um objeto EXTERNAL ACCESS INTEGRATION.
SECRET_REFERENCE - para uma referência a um objeto SECRET.

O segredo é anexado ao procedimento/função alterado com a chave credentials. Por padrão, o procedimento não está disponível para nenhuma das funções de usuário do aplicativo.

Assinatura do procedimento¶

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

Copy

Onde:

methods ARRAY representam uma matriz de assinaturas de procedimentos/funções como varchar, por exemplo, ARRAY_CONSTRUCT('PUBLIC.PROC_1(VARIANT)', 'PUBLIC.PROC_2()').

Valores retornados¶

O procedimento sempre retorna uma variante com uma estrutura de resposta de conector padrão.

No caso de uma execução bem-sucedida do procedimento:

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

A execução do procedimento é concluída com êxito mesmo quando as assinaturas de procedimento/função passadas como argumentos não representam objetos existentes ou quando um aplicativo não tem acesso a esses objetos. O processo de alteração desse tipo de procedimento/função é ignorado e o processo geral continua.

Em caso de falha:

{
  "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>"
}
Copy
Atenção

O procedimento não gera nenhum erro se ocorrer um erro durante a execução. Cada erro é incluído na resposta do conector e mapeado para o response_code apropriado, o que permite validar o resultado do procedimento e usá-lo com segurança no setup.sql durante a instalação do aplicativo (caso contrário, qualquer erro não tratado poderia interromper e encerrar o processo de instalação do aplicativo).

Possíveis erros¶

EAI_UNAVAILABLE - um objeto EXTERNAL ACCESS INTEGRATION não existe ou um aplicativo não tem o privilégio USAGE nele.
SECRET_UNAVAILABLE - um objeto SECRET não existe ou um aplicativo não tem pelo menos um privilégio READ nele.
INTERNAL ERROR - esse código de resposta é retornado em caso de ocorrências de erros inesperados.

Exemplo de uso¶

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

Copy

PUBLIC.SETUP_EXTERNAL_INTEGRATION()¶

Essa é uma versão bruta dos procedimentos descritos acima, que também é usada por eles. O procedimento altera outros procedimentos ou funções, cujas assinaturas são passadas como argumento do procedimento em uma matriz, com nomes do objeto EXTERNAL ACCESS INTEGRATION e SECRET que também são passados como argumentos do procedimento. Esse procedimento dá ao desenvolvedor a liberdade de decidir como fornecer informações sobre objetos relacionados ao acesso externo ao procedimento.

O segredo é anexado ao procedimento/função alterado com a chave credentials. Por padrão, o procedimento não está disponível para nenhuma das funções de usuário do aplicativo.

O uso desse procedimento é recomendado somente quando não há possibilidade de usar os procedimentos descritos acima, que usam referências com nomes predefinidos ou nomes de objetos armazenados em chaves predefinidas na configuração da conexão.

Assinatura do procedimento¶

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

Copy

Onde:

eai_idf VARCHAR - representa um identificador de um objeto EXTERNAL_ACCESS_INTEGRATION. Se você quiser passar um nome de referência, precisará envolvê-lo da seguinte forma: 'reference(\'<reference_name>\')'
secret_idf VARCHAR - representa um identificador de um objeto SECRET. Se você quiser passar um nome de referência, precisará envolvê-lo da seguinte forma: 'reference(\'<reference_name>\')'
methods ARRAY representam uma matriz de assinaturas de procedimentos/funções como varchar, por exemplo, ARRAY_CONSTRUCT('PUBLIC.PROC_1(VARIANT)', 'PUBLIC.PROC_2()').

Valores retornados¶

O procedimento sempre retorna uma variante com uma estrutura de resposta de conector padrão.

No caso de uma execução bem-sucedida do procedimento:

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

A execução do procedimento é concluída com êxito mesmo quando as assinaturas de procedimento/função passadas como argumentos não representam objetos existentes ou quando um aplicativo não tem acesso a esses objetos. O processo de alteração desse tipo de procedimento/função é ignorado e o processo geral continua.

Em caso de falha:

{
  "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>"
}
Copy
Atenção

O procedimento não gera nenhum erro se ocorrer um erro durante a execução. Cada erro é incluído na resposta do conector e mapeado para o response_code apropriado, o que permite validar o resultado do procedimento e usá-lo com segurança no setup.sql durante a instalação do aplicativo (caso contrário, qualquer erro não tratado poderia interromper e encerrar o processo de instalação do aplicativo).

Possíveis erros¶

EAI_UNAVAILABLE - um objeto EXTERNAL ACCESS INTEGRATION não existe ou um aplicativo não tem o privilégio USAGE nele.
SECRET_UNAVAILABLE - um objeto SECRET não existe ou um aplicativo não tem pelo menos um privilégio READ nele.
INTERNAL ERROR - esse código de resposta é retornado em caso de ocorrências de erros inesperados.

Exemplo de uso¶

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)')
);

Copy

Quando você quiser usar esse procedimento no script setup.sql e os nomes dos objetos SECRET e EXTERNAL ACCESS INTEGRATION forem armazenados de forma diferente da recomendada pelo Native SDK for Connectors, será necessário recuperar esses valores de alguma forma. Nesse caso, você pode usar o mecanismo 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;
$$
;

Copy