Nota:

Richiama la funzione personalizzata di Oracle Cloud Infrastructure con l'evento di notifica e pubblica il messaggio aggiornato allo strumento di collaborazione Lark

Introduzione

I clienti di Oracle Cloud Infrastructure (OCI) ricevono notifiche tramite gli argomenti di notifica OCI sottoscritti, che coprono eventi quali eventi dell'istanza, allarmi, annunci della console e molto altro. Questi argomenti sottoscritti supportano anche le funzioni OCI come destinazioni delle notifiche, consentendo ai clienti di richiamare una funzione personalizzata durante l'evento di notifica e inviare dettagli di notifica aggiornati ai canali di comunicazione che supportano il richiamo delle API. In questa esercitazione viene illustrato come inoltrare queste notifiche aggiornate a Lark, una piattaforma di collaborazione aziendale con API di messaggistica.

Utilizzando una funzione OCI personalizzata, è possibile recuperare vari dati ed eseguire azioni, di seguito sono riportati alcuni esempi come:

Questa esercitazione fornisce una panoramica completa su come attivare una funzione OCI personalizzata in risposta all'evento energetico di un'istanza, ad esempio STOP. Gli utenti hanno la flessibilità di personalizzare questa funzione e di attivarla in base a vari argomenti di notifica OCI sottoscritti. Per ulteriori informazioni sulle funzioni OCI, vedere Panoramica delle funzioni OCI.

Obiettivo

Le funzioni OCI consentono di scrivere codice personalizzato che è possibile richiamare in base alla notifica OCI, all'argomento Notifica sottoscritta dell'annuncio OCI, all'evento dell'istanza di computazione e a molto altro ancora. In questa esercitazione è stata creata una funzione personalizzata scritta in codice Python che viene richiamata in base a un evento di notifica e pubblica il messaggio aggiornato allo strumento di collaborazione Lark utilizzando un URL webhook all'interno del codice. In questo modo è possibile includere e aggiornare le informazioni aggiuntive necessarie che l'utente finale può utilizzare.

Prerequisiti

Destinatari

Questa esercitazione è destinata agli amministratori e ai professionisti del provider di Cloud Service.

Architettura

Di seguito è riportato un esempio di topologia del caso d'uso e architettura di alto livello della soluzione.

Architettura di connettività tra più aree di interconnessione di Azure OCI

È possibile fare riferimento a questa architettura quando si desidera creare una funzione OCI personalizzata e richiamarla in base all'evento di notifica. È possibile seguire una serie di attività descritte in questa esercitazione per impostare e convalidare questa architettura.

Task 1: Creazione di un gruppo dinamico

I gruppi dinamici ti consentono di raggruppare le istanze di computazione OCI come attori "principali" (simile ai gruppi di utenti).

Nota: per creare gruppi dinamici sono necessari privilegi di amministratore.

  1. Collegarsi all'account della tenancy della console OCI.

  2. Dal menu Servizi selezionare Identità e sicurezza, quindi selezionare Gruppi dinamici nella sezione Identità.

  3. Fare clic su Crea gruppo dinamico.

  4. Immettere un valore significativo per Nome e Descrizione.

  5. Nella sezione Regola 1 aggiungere la riga seguente:

    ALL {resource.type = 'fnfunc', resource.compartment.id = 'ocid1.compartment.oc1', instance.compartment.id = 'ocid1.compartment.XXXXX'}

    Nota:

    • Sostituire l'ID compartimento con l'ID compartimento desiderato.
    • È inoltre possibile includere un OCID risorsa funzione specifico nel gruppo dinamico.

  6. Fare clic su Crea per creare il gruppo dinamico come mostrato nell'immagine seguente.

    Gruppo dinamico creato

Task 2: Crea criterio IAM OCI del gruppo dinamico

Oracle Cloud Infrastructure Identity and Access Management (OCI IAM) consente di controllare chi ha accesso alle risorse cloud. Per garantire il corretto funzionamento di questa architettura, è necessario concedere l'accesso alle faas function as a service per il calcolo, le reti e diversi altri servizi.

  1. Nel menu Servizi selezionare Identità e sicurezza, quindi nella sezione Identità selezionare Criteri.

  2. Fare clic su Crea criterio.

  3. Immettere un nome e una descrizione appropriati e assicurarsi di selezionare il compartimento corretto (in questo esempio, verrà utilizzato il nome del compartimento oc-demo).

  4. Nella sezione Programma di generazione criteri, assicurarsi di abilitare l'opzione Mostra editor manuale e incollare le righe seguenti:

    Allow dynamic-group <dynamic_group_name> to read instances in compartment <compartment_name_path>

    Allow dynamic-group <dynamic_group_name> to read vnics in compartment <compartment_name_path>

    Allow dynamic-group <dynamic_group_name> to read vnic-attachments in compartment <compartment_name_path>

    Nota: sostituire il nome dynamic_group_name e compartment_name_path con i valori desiderati.

  5. Fare clic su Crea per creare il criterio a livello radice o a livello di compartimento come mostrato nell'immagine seguente.

    Criterio IAM creato

Task 3: creare un repository per memorizzare l'immagine della funzione personalizzata

Container Registry consente di memorizzare, condividere e gestire le immagini dei container (ad esempio, le immagini Docker) in un registro gestito da Oracle.

  1. Nella console aprire il menu del servizio e fare clic su Servizi per sviluppatori. In Container fare clic su Container Registry.

  2. Fare clic su Crea repository.

  3. Nella finestra di dialogo Crea repository specificare il compartimento e il nome repository desiderati e lasciarlo Privato.

  4. Fare clic su Crea repository per creare correttamente il registro container nel compartimento specificato, come mostrato nella seguente immagine.

    Repository Container Registry creato

Task 4: creare una rete cloud virtuale con subnet per memorizzare l'applicazione della funzione.

Una rete cloud virtuale (VCN, Virtual Cloud Network) è una rete definita nell'infrastruttura OCI. Include subnet, tabelle di instradamento e gateway.

Nota: se si dispone già di una VCN, la subnet creata in precedenza è possibile saltare questo task e procedere con il task 5.

  1. Fare clic sul menu dei servizi accanto all'angolo in alto a sinistra della console Web OCI.

  2. In Networking selezionare Reti cloud virtuali.

  3. Nella pagina Reti cloud virtuali, fare clic su Avvia procedura guidata VCN.

  4. Selezionare Crea VCN con connettività Internet e fare clic su Avvia VCN guidato.

  5. Completare la configurazione della VCN, quindi fare clic su Avanti

  6. Fare clic su Crea e le reti cloud virtuali con subnet devono essere create correttamente come mostrato nell'immagine seguente.

    Rete virtuale creata con una subnet

Task 5: Creare un'applicazione per memorizzare le funzioni

  1. Aprire il menu del servizio e fare clic su Servizi per sviluppatori. In Funzioni fare clic su Applicazioni.

  2. Fare clic su Crea applicazione.

  3. Nella finestra Crea applicazione selezionare il nome dell'applicazione (ad esempio, l'applicazione funzione), selezionare la VCN creata in Task 4 e selezionare la subnet pubblica.

  4. Fare clic su Crea e l'applicazione funzione deve essere creata correttamente come mostrato nell'immagine seguente.

    Applicazione funzione creata

Task 6: distribuire la funzione per memorizzare le funzioni

Questo passo utilizzerà l'archivio zip che può essere scaricato dalla sezione Prerequisiti di questa esercitazione.

  1. Passare alla console cloud OCI e fare clic su Strumenti sviluppatore, Cloud Shell.

    Avvia Cloud Shell

  2. Dopo aver fatto clic sul pulsante Avvia Cloud Shell, alla fine della pagina verrà visualizzata una nuova finestra con shell di piccole dimensioni. Nell'angolo superiore destro di tale finestra, fare clic sul menu della ruota dentata e selezionare Carica.

    Carica file ZIP

  3. Caricare il file zip disponibile nella sezione Prerequisiti di questa esercitazione e andare alla directory copiata.

  4. Il file func.py verrà visualizzato come segue e creato per garantire che sia possibile leggere la notazione JSON di notifica, nonché aggiungere altri campi come i dettagli dell'indirizzo IP e utilizzare il messaggio aggiornato per inviare il messaggio all'URL del webhook Lark.

    • parse_message: notazione JSON di notifica di lettura funzione e messaggio di aggiornamento
    • get_ip_address: funzione che utilizza la libreria client di computazione e di rete per leggere dettagli aggiuntivi quali, ad esempio, l'indirizzo IP basato sull'OCID risorsa dell'istanza.
    • make_post: funzione per creare un post nel canale Lark utilizzando l'URL del webhook.

    Nota:

    • Stiamo utilizzando l'SDK python OCI, ma è possibile eseguire personalizzazioni in base ad altre lingue supportate utilizzando gli SDK go/java.
    • È necessario aggiornare l'URL del webhook Lark o altri strumenti di collaborazione come Slack.
    • È possibile personalizzare questa funzione in base alle proprie esigenze. È stato utilizzato un determinato payload JSON di notifica per leggere i valori, ma è anche possibile utilizzare il file JSON dell'annuncio della console o altri file JSON dell'evento.
    ###
This is a sample code,
End user can modify as needed
###
import io
import oci
import json
import logging
import requests

"""
Read Notification Message
Add IP address of Resource.
"""
def parse_message(body):
    notification = ""
    ocid = ""
    type = body["source"]
    description = body["eventType"]
    compartment_id = body["data"]["compartmentId"]
    compartment_name = body["data"]["compartmentName"]
    affected_resources = ""

    if len(body["data"]) > 0:
        signer = oci.auth.signers.get_resource_principals_signer()
        affected_resources = "Affected Resources: "
        ocid = body["data"]["resourceId"]
        notification_reason = body["data"]["additionalDetails"]["instanceActionType"]
        affected_resources += "\nResource OCID: " + ocid
        resource_ip_address = get_ip_address(signer, ocid)
        affected_resources += "\nResource Private IP Address: " + resource_ip_address

    notification = type + " " + "\n\n" + compartment_name + " - " + compartment_id + "\n\n" + description + "\n\n" + affected_resources + "\n\n" + notification_reason
    logging.getLogger().debug(notification)

    make_post(notification)

"""
Get Resource IP address
based of resource OCID.
"""
def get_ip_address(signer, resource_id):
    compute_client = oci.core.ComputeClient(config={}, signer=signer)
    network_client = oci.core.VirtualNetworkClient(config={}, signer=signer)
    instance_details = compute_client.get_instance(instance_id=resource_id).data
    vnic_response = compute_client.list_vnic_attachments(compartment_id=instance_details.compartment_id, instance_id=resource_id)
    vnics = vnic_response.data

    for vnic in vnics:
        vnic_details = network_client.get_vnic(vnic_id=vnic.vnic_id).data
        private_ip = vnic_details.private_ip
        return private_ip

"""
Post a Message to Lark.
You can also use OCI Vault/Secret to store Lark credentials and access them here.
"""
def make_post(post_text):
    url = "https://open.larksuite.com/open-apis/bot/v2/hook/XXXX"
    headers = {
        "Content-Type": "application/json"
    }
    req_body = {
        "msg_type": "text",
        "content": {
            "text": post_text
        }
    }
    payload = json.dumps(req_body)
    try:
        post_response=requests.post(url=url, data=payload, headers=headers)
    except Exception as e:
        logging.getLogger().error(e)
        return

    response_dict = json.loads(post_response.text)
    code = response_dict.get("StatusCode", -1)

    if code != 0:
        logging.getLogger().error("error sending post text, code: " + str(code))
    return

def to_bool(a):
    return True if a == "True" else False

"""This is the function entry point.
ctx will contain function variables defined in OCI console,
data contains the payload
"""
def handler(ctx, data: io.BytesIO = None):
    try:
        cfg = dict(ctx.Config())
        for a in cfg:
            cfg[a]=to_bool(cfg[a])

    except Exception as e:
        print('ERROR: Missing configuration keys', e, flush=True)
        logging.getLogger().debug(cfg)
        return 'error parsing config keys: ' + str(ex)

    try:
        raw_body = data.getvalue()
        body = json.loads(raw_body)
        logging.getLogger().info(body)
        parse_message(body)
    except (Exception, ValueError) as ex:
        logging.getLogger().error('error parsing json payload: ' + str(ex))
        return 'error parsing json payload: ' + str(ex)

  5. Distribuire la funzione utilizzando il comando fn deploy per creare l'immagine del docker di funzioni e le dipendenze associate in cloud shell. Puoi eseguire il PUSH dell'immagine nel registro Docker specificato e distribuire la funzione in Funzioni OCI nell'applicazione creata in precedenza.

    fn -v deploy --app <app-name>

    Ad esempio:

    fn -v deploy --app function-app

    Nota: è possibile visualizzare il file func.yaml. Vedere i dettagli richiesti per l'immagine docker della funzione.

  6. Una volta distribuita, la funzione deve essere creata correttamente come mostrato nella seguente immagine.

    Funzione creata

Task 7: sottoscrizione della funzione a un argomento

  1. Aprire il menu del servizio e fare clic su Servizi per sviluppatori. In Integrazione applicazioni fare clic su Notifiche. Assicurarsi di trovarsi nel compartimento corretto.

  2. Fare clic su Crea argomento.

  3. Impostare un nome appropriato, quindi fare clic su Crea.

  4. Dopo aver creato l'argomento, selezionarlo dall'elenco di argomenti.

  5. Nella finestra Argomenti selezionare Sottoscrizioni dal lato sinistro in Risorse e fare clic su Crea sottoscrizione.

  6. Nella finestra laterale Crea sottoscrizione selezionare il protocollo Funzioni, selezionare il compartimento, l'applicazione e la funzione creati in Task 6.

  7. Fare clic su Crea. La sottoscrizione della funzione a un argomento deve essere riuscita, come mostrato nell'immagine seguente.

    Iscrizione alla notifica creata

Task 8: Creare un'istanza e una regola evento di notifica

Per convalidare la funzione in questo passo, verrà creato un'istanza e un argomento di notifica di creazione associato in Task 7 a un evento come istanza arrestata.

  1. Nella console passare a Computazione, Istanze per creare un'istanza di computazione.

  2. Fare clic sull'icona Crea istanza e fornire i dettagli richiesti:

    • Nome istanza
    • Compartimento dell'istanza
    • Selezionare l'AD desiderato
    • Selezionare la VCN di rete e la subnet pubblica
    • Copia e incolla la chiave ssh pubblica
    • Fare clic su Crea.

  3. Attendere che l'istanza visualizzi in esecuzione, quindi eseguire il login all'istanza utilizzando il comando seguente.

    ssh opc@<public ip> -i <private key>

  4. Passare alla finestra Computazione, Istanze, Dettagli istanza, Notifica per creare un evento di notifica.

  5. Fare clic su Crea notifica e selezionare un modello QuickStart come Modifica stato istanza in arrestata.

  6. Immettere il nome della regola evento e selezionare l'argomento creato da Task 7, quindi fare clic su Crea notifica. La regola evento di notifica deve essere creata correttamente in un argomento sottoscritto, come mostrato nell'immagine seguente.

    Regola evento creata

Task 9: Convalida regola evento notifica

In questo passo si arresta l'istanza che attiverà l'argomento di notifica associato. È inoltre possibile includere l'indirizzo e-mail per visualizzare il payload delle notifiche.

  1. Passare all'istanza creata e fare clic su Arresta.

  2. Una volta arrestata l'istanza, dovresti ricevere un messaggio di posta elettronica tramite l'argomento di notifica sottoscritto e la funzione deve essere attivata.

  3. Confermare di aver ricevuto un'e-mail come mostrato nella seguente immagine.

    E-mail argomento di notifica OCI

  4. Andare al canale scuro utilizzato per includere l'URL del webhook.

    Messaggio di notifica Lark

    Nota: se questo messaggio di aggiornamento viene visualizzato con attenzione dall'e-mail ricevuta, in base alla funzione personalizzata è stato incluso l'indirizzo IP dell'istanza mediante SSL sdk.

  5. [Facoltativo] È inoltre possibile associare questo argomento di notifica ai dettagli della funzione di aggiornamento in base ai dettagli dell'annuncio della console. Puoi seguire questa documentazione per ulteriori informazioni.

    Nota: è necessario modificare il codice funzione personalizzato per assicurarsi di leggere il payload JSON corretto e di modificarlo di conseguenza. È possibile utilizzare il payload JSON dell'annuncio di esempio ricevuto dai team di servizio.

    Sottoscrizione notifica annuncio OCI

Passi successivi

Questa esercitazione descrive a un utente finale come utilizzare una funzione personalizzata per leggere il payload JSON di notifica e utilizzare le librerie SDK OCI per aggiornare il payload e pubblicare messaggi in strumenti di collaborazione comuni come Lark. È possibile espandere questa funzione per aggiungere ulteriori dettagli, ad esempio Tag risorse, Dettagli di rete e altro ancora.

Approvazioni

Altre risorse di apprendimento

Esplora altri laboratori su docs.oracle.com/learn o accedi a contenuti di formazione gratuiti sul canale YouTube di Oracle Learning. Inoltre, visitare education.oracle.com/learning-explorer per diventare Explorer di Oracle Learning.

Per la documentazione sul prodotto, visitare il sito Oracle Help Center.