Chiama Web Services da Autonomous AI Database

Fornisce i dettagli per l'utilizzo di UTL_HTTP per sottomettere una richiesta HTTP su un host pubblico.

Ad esempio, per inviare una richiesta HTTP per un host pubblico www.example.com, creare una lista di controllo dell'accesso per l'host:

BEGIN
   DBMS_NETWORK_ACL_ADMIN.APPEND_HOST_ACE(
         host => 'www.example.com',
         ace =>  xs$ace_type( privilege_list => xs$name_list('http'),
                              principal_name => 'ADMIN',
                              principal_type => xs_acl.ptype_db));
END;

Quindi sottomettere la richiesta HTTP:

SELECT UTL_HTTP.REQUEST(url => 'https://www.example.com/') FROM dual;

Consulta le Note sul package PL/SQL per Autonomous AI Database per informazioni sulle limitazioni per UTL_HTTP su Autonomous AI Database.

Descrive la procedura per utilizzare UTL_HTTP per inviare una richiesta HTTP su un host privato.

Per sottomettere una richiesta a un host di destinazione su un endpoint privato, l'host di destinazione deve essere accessibile dalla VCN Oracle Cloud Infrastructure del database di origine. Ad esempio, è possibile connettersi all'host di destinazione quando:

• Sia il database di origine che l'host di destinazione si trovano nella stessa VCN di Oracle Cloud Infrastructure.

• Il database di origine e l'host di destinazione si trovano in VCN Oracle Cloud Infrastructure diverse abbinate.

• L'host di destinazione è una rete in locale connessa alla VCN Oracle Cloud Infrastructure del database di origine mediante FastConnect o VPN.

È inoltre possibile effettuare chiamate UTL_HTTP con un wallet gestito dal cliente quando Autonomous AI Database si trova in un endpoint privato. Per ulteriori informazioni, vedere Come effettuare chiamate esterne utilizzando un wallet gestito dal cliente.

Per effettuare una richiesta UTL_HTTP a una destinazione su un endpoint privato, effettuare le operazioni riportate di seguito.

1. Creare una lista di controllo dell'accesso per l'host.

   Ad esempio:

   BEGIN
      DBMS_NETWORK_ACL_ADMIN.APPEND_HOST_ACE(
            host => 'www.example.com',
            ace => xs$ace_type( privilege_list => xs$name_list('http'),
                                principal_name => 'ADMIN',
                                principal_type => xs_acl.ptype_db),
                                private_target => TRUE);
   END;
   /

   Come illustrato in questo esempio, quando si crea una lista di controllo dell'accesso per l'host, specificare il parametro private_target con il valore TRUE.

   Nota
   
   Se si imposta la proprietà del database ROUTE_OUTBOUND_CONNECTIONS, l'impostazione del parametro private_target su TRUE non è obbligatoria in questa API. Per ulteriori informazioni, vedere Sicurezza avanzata per le connessioni in uscita con endpoint privati.

2. Sottomettere la richiesta HTTP:

   SELECT UTL_HTTP.REQUEST(
                   url => 'https://www.example.com/',
                   https_host => 'www.example.com') 
                FROM dual;

Consulta le Note sul package PL/SQL per Autonomous AI Database per informazioni sulle limitazioni per UTL_HTTP su Autonomous AI Database.

Quando l'istanza di Autonomous AI Database si trova su un endpoint privato, è possibile utilizzare un proxy per sottomettere richieste HTTP con UTL_HTTP.

1. Impostare l'ACL HTTP_PROXY sul server proxy.

   Ad esempio:

   BEGIN
     DBMS_NETWORK_ACL_ADMIN.APPEND_HOST_ACE(
          host =>'www-proxy-example.com',
          ace  => xs$ace_type(privilege_list => xs$name_list('HTTP_PROXY'),
                              principal_name => 'APPUSER1',
                              principal_type => xs_acl.ptype_db),
                              private_target => TRUE);
   END;
   /

   Come illustrato in questo esempio, quando si crea una lista di controllo dell'accesso per il server proxy, specificare il parametro private_target con il valore TRUE.

   Nota
   
   Se si imposta la proprietà del database ROUTE_OUTBOUND_CONNECTIONS, l'impostazione del parametro private_target su TRUE non è obbligatoria in questa API. Per ulteriori informazioni, vedere Sicurezza avanzata per le connessioni in uscita con endpoint privati.
2. Impostare l'ACL HTTP sul server Web remoto.

   Ad esempio:

   BEGIN
     DBMS_NETWORK_ACL_ADMIN.APPEND_HOST_ACE(
           host =>'example.com',
           ace => xs$ace_type( privilege_list => xs$name_list('HTTP'),
                               principal_name => 'APPUSER1',
                               principal_type => xs_acl.ptype_db)
   END;
   /

3. Impostare il wallet e il proxy per UTL_HTTP.

   Ad esempio:

   BEGIN
      UTL_HTTP.SET_WALLET('');
      UTL_HTTP.SET_PROXY('www-proxy-example:80');
   END;
   /

4. Sottomettere una richiesta HTTP:

   SELECT UTL_HTTP.REQUEST(    
                       url         => 'https://www.example.com/',
                       https_host  => 'www.example.com')
                FROM dual;

Descrive come passare un oggetto credenziale alla procedura UTL_HTTP.SET_CREDENTIAL.

La procedura UTL_HTTP.SET_CREDENTIAL imposta le informazioni di autenticazione HTTP nell'intestazione della richiesta HTTP. Il server Web necessita di queste informazioni per autorizzare la richiesta.

La procedura UTL_HTTP.SET_CREDENTIAL consente di passare gli oggetti delle credenziali per impostare l'autenticazione HTTP. Gli oggetti delle credenziali sono oggetti dello schema, pertanto è possibile accedervi solo da utenti con privilegi e consentire di configurare privilegi a livello di schema per controllare le credenziali. Il passaggio di oggetti credenziali è un modo appropriato e sicuro per memorizzare e gestire nome utente/password/chiavi da utilizzare per l'autenticazione.

La procedura UTL_HTTP.SET_CREDENTIAL è un'alternativa sicura e conveniente alla procedura UTL_HTTP.SET_AUTHENTICATION.

Esempio

...
UTL_HTTP.SET_AUTHENTICATION (l_http_request, 'web_app_user', 'xxxxxxxxxxxx');
...

Come mostrato nell'esempio precedente, quando si richiama la procedura SET_AUTHENTICATION, è necessario passare il nome utente/password in chiaro come parte dei parametri formali PL/SQL. Potrebbe essere necessario incorporare il nome utente/password in vari script di automazione PL/SQL o cron. Il passaggio di password con testo in chiaro è un problema di conformità affrontato nella procedura UTL_HTTP.SET_CREDENTIAL.

Per ulteriori informazioni, vedere SET_AUTHENTICATION Procedure e SET_AUTHENTICATION_FROM_WALLET Procedure.

Sintassi UTL_HTTP.SET_CREDENTIAL

UTL_HTTP.SET_CREDENTIAL (
    r          IN OUT NOCOPY req,
    credential IN VARCHAR2,
    scheme     IN VARCHAR2 DEFAULT 'Basic',
    for_proxy  IN BOOLEAN  DEFAULT FALSE);

Esempio per passare un oggetto credenziale nella procedura SET_CREDENTIAL:

• Creare un oggetto credenziale:

  BEGIN DBMS_CLOUD.CREATE_CREDENTIAL (
      credential_name => 'HTTP_CRED',
      username        => 'web_app_user',
      password        => '<password>' );
  END;

  In questo modo viene creato un oggetto credenziale che crea una coppia di nome utente/password memorizzata.

  Per ulteriori informazioni, vedere CREATE_CREDENTIAL Procedure.

  Per ulteriori informazioni, vedere Specifica delle credenziali del job scheduler.

• Richiamare la procedura UTL_HTTP.SET_CREDENTIAL:

  DECLARE
        l_http_request  UTL_HTTP.REQ;
      BEGIN 
        l_http_request := UTL_HTTP.BEGIN_REQUEST('https://www.example.com/v1/dwcsdev/NAME/dwcs_small_xt1.csv');
        UTL_HTTP.SET_CREDENTIAL (l_http_request, 'HTTP_CRED','BASIC');
        ...
  END;
  

  In questo esempio viene creata una richiesta richiamando la procedura BEGIN_REQUEST e vengono impostate le informazioni di autenticazione HTTP nell'intestazione della richiesta HTTP richiamando la procedura SET_CREDENTIAL. Il server Web necessita di queste informazioni per autorizzare la richiesta. Il valore l_http_request è la richiesta HTTP, HTTP_CRED è il nome delle credenziali e BASIC è lo schema di autenticazione HTTP.

Per ulteriori informazioni, vedere UTL_HTTP.

Consulta le Note sul package PL/SQL per Autonomous AI Database per informazioni sulle limitazioni per UTL_HTTP su Autonomous AI Database.

Quando si utilizza il foglio di lavoro SQL Comandi SQL di Oracle APEX o Database Actions per eseguire più comandi SQL sequenziali, i comandi possono essere eseguiti in sessioni di database diverse che non salvano lo stato di un'istruzione precedente. Questo comportamento è diverso dai client SQL desktop, ad esempio SQL*Plus e SQL Developer, che mantengono una connessione persistente al database.

I comandi SQL di Oracle APEX e le sottomissioni del foglio di lavoro SQL di Database Actions a un'istanza di Autonomous AI Database sono senza conservazione dello stato. Ciò significa che l'esecuzione di singole istruzioni SQL e PL/SQL può salvare lo stato nella memoria del database, ad esempio quando si sottomette un comando per utilizzare un wallet, ma lo stato potrebbe essere cancellato prima di eseguire l'istruzione successiva.

Visualizzare la tabella riportata di seguito per i passi che consentono di mantenere lo stato della memoria del database tra le esecuzioni delle istruzioni per i comandi SQL sottomessi ad Autonomous AI Database.

Ad esempio, utilizzare il blocco di codice seguente per eseguire un comando utl_http.request() che utilizza un wallet gestito dal cliente:

SELECT utl_http.request(url => 'https://api.example.com/', wallet_path => 'file:path_to_wallet', wallet_password => 'password' ) FROM DUAL";

Confrontare l'esecuzione con due istruzioni consecutive che potrebbero non riuscire se il comando utl_http.set_wallet() e l'istruzione utl_http.request() vengono eseguiti singolarmente, anziché come un singolo blocco di codice:

EXEC utl_http.set_wallet('file:WALLET_DIR/wallet.sso', 'password');
SELECT utl_http.request('https://api.example.com/') FROM DUAL;

È possibile configurare Autonomous AI Database in modo che invii le informazioni di identità del database come intestazioni HTTP personalizzate durante l'esecuzione di richieste HTTP in uscita.

ALTER DATABASE PROPERTY SET DATABASE_IDENTITY_NETWORK_HEADERS = '[
"DATABASE_NAME",
"REGION",
"DATABASE_OCID"
]';

ALTER DATABASE PROPERTY SET DATABASE_IDENTITY_NETWORK_HEADERS = '[
"DATABASE_NAME",
"REGION",
"TENANT_OCID",
"DATABASE_OCID",
"COMPARTMENT_OCID",
"CLOUD_DOMAIN",
"CLIENT_IP_ADDRESS"
]';

ALTER DATABASE PROPERTY SET DATABASE_IDENTITY_NETWORK_HEADERS_DOMAINS = '*';

ALTER DATABASE PROPERTY SET DATABASE_IDENTITY_NETWORK_HEADERS_DOMAINS = 'objectstorage.oraclecloud.com';

ALTER DATABASE PROPERTY SET DATABASE_IDENTITY_NETWORK_HEADERS_DOMAINS = 'oraclecloud.com, example.com';

X-ADB-Source-Database=
  {"databaseName":"MYDATABASENAME",
   "region":"region_identifier",
   "tenantOcid":"tenant_ocid",
   "databaseOcid":"database_ocid",
   "compartmentOcid":"compartment_ocid",
   "clientIpAddress":"client_ip_address"}