Configurazione di Jira Cloud

Anteprima pubblica:le funzionalità di ricerca e azioni federate sono in Anteprima pubblica. Questa funzionalità è soggetta ai "Termini delle Offerte pre-GA" nella sezione Termini di servizio generali dei Termini specifici dei servizi. Le funzionalità pre-GA sono disponibili "così come sono" e potrebbero avere un supporto limitato. Per saperne di più, consulta le descrizioni della fase di lancio.

Questa pagina descrive come configurare una configurazione di terze parti prima di creare il datastore Jira Cloud.

Configurare l'autenticazione e le autorizzazioni

Devi configurare l'autenticazione e le autorizzazioni nel centro di amministrazione Atlassian. Questo è fondamentale per consentire al connettore di accedere ai dati e sincronizzarli. Il connettore Jira Cloud supporta vari metodi di autenticazione, ad esempio le credenziali client OAuth o i token API.

Crea un'app OAuth 2.0

Per creare un'app OAuth 2.0 per l'autenticazione, segui questi passaggi per configurare l'applicazione in Atlassian Developer Console e ottenere l'ID client e il client secret necessari.

Verificare l'accesso di amministratore dell'organizzazione Jira

Per verificare l'accesso di amministratore dell'organizzazione Jira:

1. Accedi ad Atlassian con le tue credenziali utente.

2. Seleziona l'app Jira.

3. Fai clic su Impostazioni.

   Se vedi l'opzione System (Sistema) in Jira settings (Impostazioni Jira), hai accesso come amministratore dell'organizzazione Jira. In caso contrario, chiedi all'amministratore dell'organizzazione Jira di fornire l'accesso.

Crea un'app OAuth 2.0

Per creare un'app OAuth 2.0:

1. Accedi all'Atlassian Developer Console.

2. Fai clic sull'icona del profilo e seleziona Developer console (Console per gli sviluppatori).

3. Nella pagina Console, fai clic su Crea e seleziona Integrazione OAuth 2.0.

4. Nella pagina di creazione dell'app:

   1. Inserisci un nome per l'app.

   2. Seleziona la casella di controllo per accettare i termini per gli sviluppatori di Atlassian.

   3. Fai clic su Crea.

5. Nella pagina dell'app:

   1. Nel menu di navigazione, fai clic su Autorizzazione.

   2. Nella tabella Authorization type (Tipo di autorizzazione), seleziona Add (Aggiungi) per OAuth 2.0 (3LO).

6. Nel campo Callback URL (URL di callback), inserisci https://vertexaisearch.cloud.google.com/console/oauth/jira_oauth.html.

7. Fai clic su Salva modifiche.

Ottieni l'ID client e il client secret

Per ottenere l'ID client e il client secret:

1. Nella pagina dell'app, fai clic su Distribuzione nel menu di navigazione.

2. Nella pagina Distribuzione, segui questi passaggi:

   1. Nella sezione Controlli di distribuzione, seleziona Modifica.
   2. Nella sezione Stato della distribuzione, seleziona Condivisione per attivare la modifica di altri campi.
   3. Compila i seguenti campi obbligatori con le informazioni richieste:
      1. In Vendor (Fornitore), inserisci Google.
      2. In Privacy policy (Norme sulla privacy), inserisci https://policies.google.com.
      3. Per Does your app store personal data? (La tua app memorizza dati personali?), seleziona Yes (Sì).
      4. Seleziona la casella di controllo I confirm that I've implemented the personal data reporting API (Confermo di aver implementato l'API per la generazione di report sui dati personali). Per saperne di più, consulta Personal data reporting API (API per la generazione di report sui dati personali).
   4. Fai clic su Salva modifiche.

3. Nella pagina dell'app:

   1. Nel menu di navigazione, fai clic su Impostazioni.
   2. Nella pagina delle impostazioni, copia l'ID client e il client secret.

Ottenere un ID istanza e un URL istanza

1. Ottieni l'ID istanza:

   1. Apri una nuova scheda, copia l'URL dell'istanza e aggiungi /_edge/tenant_info all'URL dell'istanza. Ad esempio, https://YOUR_INSTANCE.atlassian.net/_edge/tenant_info.
   2. Vai al link per trovare il valore di cloudId. cloudId è l'ID istanza.

2. Ottieni l'URL dell'istanza:

   1. Vai su atlassian.net e accedi con il tuo account amministratore.
   2. Seleziona l'app che desideri sincronizzare. Ad esempio, sincronizza la prima app.
   3. Trova l'URL dell'istanza (il sottodominio nella barra degli indirizzi).

Concedi ruoli di amministratore

Per concedere all'amministratore Jira il ruolo Discovery Engine Editor nella console Google Cloud , segui questi passaggi:

1. Nella console Google Cloud , vai alla pagina Gemini Enterprise.

2. Vai a IAM.

   Vai a IAM

3. Individua l'account utente con accesso amministratore in Jira e fai clic sull'icona Modifica .

4. Concedi all'amministratore il ruolo Discovery Engine Editor.

Per concedere a un utente un ruolo di amministratore in Atlassian:

1. Accedi ad Atlassian utilizzando un account amministratore.

2. Fai clic sull'icona del menu e seleziona la tua organizzazione. In alternativa, puoi andare ad admin.atlassian.com.

3. Nella pagina Admin (Amministrazione), fai clic sul prodotto e seleziona il pulsante Manage users (Gestisci utenti).

   

   Gestisci utenti

4. Fai clic su Groups (Gruppi) in Manage users (Gestione utenti).

5. Nella pagina Groups (Gruppi):

   1. Fai clic su Crea gruppo.
   2. Inserisci un nome per il gruppo.

   

   Crea gruppo

Questo gruppo riceve le autorizzazioni richieste dal connettore. Gli utenti aggiunti a questo gruppo ereditano queste autorizzazioni. Il connettore utilizza questo gruppo per autenticarsi e recuperare i documenti.

1. Nella pagina del gruppo, fai clic su Aggiungi prodotto.

2. Seleziona User access admin (Amministratore accesso utente) come ruolo per Jira.

3. Seleziona Product admin (Amministratore prodotto) come ruolo per Jira administration (Amministrazione Jira).

   

   Amministratore accesso utente Jira

4. Fai clic su Concedi l'accesso.

5. Fai clic su Add group members (Aggiungi membri del gruppo) per aggiungere un account utente o membri del gruppo che il connettore utilizza per l'autenticazione e l'accesso alle risorse richieste.

   

   Aggiungere membri al gruppo

Gestisci la visibilità degli utenti

Per rendere visibile l'email dell'utente a chiunque abbia un account Atlassian, procedi nel seguente modo:

1. Accedi all'Atlassian Developer Console.

2. Fai clic sull'icona del profilo e seleziona Developer console (Console per gli sviluppatori).

3. Fai clic sull'icona del profilo utente e seleziona Manage account (Gestisci account).

   

   Gestisci account

4. Vai a Profile and visibility (Profilo e visibilità).

   

   Profilo e visibilità

5. Vai a Contact (Contatto) e imposta Who can see this (Chi può vedere questo) su Anyone (Chiunque).

   

   Contatto

Per rendere visibile l'email dell'utente a chiunque in Jira:

1. Accedi ad Atlassian con le tue credenziali utente.

2. Seleziona un'app Jira.

3. Fai clic su Settings (Impostazioni) > System (Sistema).

4. Seleziona General Configuration (Configurazione generale) nel riquadro a sinistra.

5. Fai clic su Edit Settings (Modifica impostazioni).

6. Per User email visibility (Visibilità email utente), seleziona Public (Pubblica).

   

   Seleziona la visibilità dell'email

7. Fai clic su Aggiorna.

Configura gli ambiti minimi dell'applicazione

Per eseguire le azioni definite, devi configurare le seguenti autorizzazioni per il connettore Jira Cloud nella piattaforma Atlassian.

1. Nella pagina dell'applicazione, fai clic su Permissions (Autorizzazioni).

2. Vai all'API Jira e fai clic su Add (Aggiungi).

   Nota: dopo aver aggiunto l'API Jira, il pulsante Configura potrebbe impiegare un po' di tempo per essere visualizzato. Se non viene visualizzato immediatamente, prova ad aggiornare la pagina o ad attendere qualche secondo.

3. Fai clic su Configura.

4. Vai alla scheda Classic scopes (Ambiti classici).

5. Fai clic su Modifica ambiti e seleziona gli ambiti classici in base alle tue esigenze dalla seguente tabella:

Modalità di connessione	Autorizzazione	Finalità
Ricerca federata e azioni	read:jira-user, read:jira-work	Necessario per recuperare e visualizzare i risultati di ricerca e i dettagli utente in tempo reale.
	write:jira-work	Consente all'assistente di modificare gli elementi di lavoro (ad es. aggiornare i campi dei problemi) e gestire i commenti o i problemi.
Solo ricerca federata	read:jira-user, read:jira-work	Obbligatorio per cercare e visualizzare problemi, progetti e profili utente.
Importazione e azioni sui dati	read:jira-work	Obbligatorio per la scansione e l'indicizzazione estese dei dati degli elementi di lavoro.
	write:jira-work	Necessario per eseguire azioni di scrittura (creazione, aggiornamenti, commenti) sugli elementi di lavoro all'interno dell'ambiente importato.
Importazione dati	read:jira-work	Obbligatorio per eseguire la scansione e l'indicizzazione dei contenuti Jira per la disponibilità della ricerca.

1. Conferma che tutti gli ambiti siano selezionati e fai clic su Salva.

2. Vai alla scheda Granular scopes (Ambiti granulari).

3. Fai clic su Modifica ambiti e seleziona gli ambiti granulari in base alle tue esigenze dalla seguente tabella:

Modalità di connessione	Autorizzazione	Finalità
Ricerca federata e azioni	write:comment:jira	Consente all'assistente di pubblicare nuovi commenti o risposte direttamente dall'interfaccia di ricerca.
	write:issue:jira	Necessario per creare nuovi problemi o apportare modifiche importanti a quelli esistenti.
Importazione e azioni sui dati	read:user:jira, read:group:jira, read:avatar:jira	Obbligatorio per la sincronizzazione dei metadati di utenti/gruppi e la visualizzazione dei profili utente.
	read:issue-security-level:jira, read:issue-security-scheme:jira	Fondamentale per controllo dell'accesso dell'accesso; garantisce che i dati importati rispettino i limiti di sicurezza di Jira.
	read:audit-log:jira	Utilizzato per monitorare le modifiche ed eseguire sincronizzazioni incrementali per mantenere aggiornati i dati importati.
	write:comment:jira	Obbligatorio per aggiungere commenti ai problemi utilizzando l'assistente.
	write:issue:jira	Consente di creare o modificare i problemi.
Importazione dati	read:user:jira, read:group:jira, read:avatar:jira	Necessario per eseguire la scansione e l'indicizzazione dei contenuti Jira e delle relazioni tra utenti.
	read:issue-security-level:jira, read:issue-security-scheme:jira	Necessario per mappare le autorizzazioni in modo che solo gli utenti autorizzati possano cercare i dati importati.
	read:audit-log:jira	Necessario per consentire al motore di sincronizzazione di identificare gli elementi aggiornati o eliminati.

1. Conferma che tutti gli ambiti siano selezionati e fai clic su Salva.

Nota: se vuoi saltare le azioni e utilizzare l'datastore per la ricerca, puoi limitare le autorizzazioni alle sole autorizzazioni read. Le autorizzazioni write sono necessarie solo per eseguire le azioni menzionate in Azioni supportate.

Installare User Identity Accessor

Per installare l'app User Identity Accessor for Jira Cloud (User Identity Accessor per Jira Cloud) sul tuo sito Jira Cloud, segui questi passaggi:

1. Vai all'Atlassian Developer Console.

2. Rivedi le autorizzazioni Read Email Address (Leggi indirizzo email) e App Storage scope (Ambito di archiviazione app) e fai clic su Get app (Scarica app).

   

   Rivedi le autorizzazioni e scarica l'app

3. Dall'elenco Select a site to install this app on (Seleziona un sito su cui installare questa app), seleziona il sito Jira su cui vuoi installare l'app. Questo elenco mostra solo i siti per cui hai accesso amministrativo.

   Nota :per installare l'app, devi essere amministratore di almeno un sito Jira.

4. Fai clic su Install (Installa) per completare l'installazione dell'app.

Configurare User Identity Accessor

Dopo aver installato l'app User Identity Accessor for Jira Cloud, configura una chiave API che il tuo sistema esterno (ad esempio, il tuo connettore Jira Cloud) utilizza per chiamare in modo sicuro il webtrigger dell'app per recuperare le email.

Accedi alla pagina di configurazione

Per accedere alla pagina di configurazione dell'app User Identity Accessor per Jira Cloud:

1. Nella tua istanza Confluence Cloud, fai clic sull'icona Settings (Impostazioni) ⚙️ nel menu di navigazione.
2. Seleziona Apps (App) dal menu.
3. Nella pagina Apps administration (Amministrazione app), individua l'app User Identity Accessor per Jira Cloud nell'elenco Manage apps (Gestisci app).

4. Fai clic su Configure (Configura) o sul link associato alla tua app. Si apre la pagina di configurazione dedicata dell'app in Jira Cloud.

   

   Configurare l'app User Identity Accessor per Jira Cloud

Configurare la chiave API

Per configurare la chiave API nella pagina di configurazione:

1. Nella sezione API Key Configuration (Configurazione chiave API), specifica la chiave segreta per autenticare le richieste al web trigger dell'app. Puoi autenticare le richieste utilizzando uno dei seguenti metodi:

   • Enter your own key (Inserisci la tua chiave): digita o incolla la tua chiave API univoca e complessa nel campo Chiave API. Utilizza una chiave di almeno 20-30 caratteri con una combinazione di lettere maiuscole, minuscole, numeri e simboli.

     

     Inserisci la tua chiave

   • Generate a key: fai clic sul pulsante Generate a key (Genera nuova chiave). Il sistema genera e visualizza una chiave casuale complessa nel campo.

     

     Genera una chiave

     Importante: copia immediatamente la chiave API visualizzata nel campo. Per motivi di sicurezza, potresti non essere in grado di visualizzare di nuovo la chiave completa dopo averla salvata o dopo aver abbandonato la pagina. In caso di perdita, devi impostarne o generarne uno nuovo.

2. Fai clic su Save API Key (Salva chiave API). Un messaggio di operazione riuscita conferma che la chiave è stata salvata in modo sicuro.

Nota: la chiave API generata o creata in questa sezione funge da valore per il campo Jira Identity Sync Forge Client Secret (Client secret Forge per la sincronizzazione delle identità in Jira) nella sezione Advanced Options (Opzioni avanzate) durante la configurazione del connettore.

Testa la configurazione dell'app

Verifica che l'app User Identity Accessor per Jira Cloud sia configurata correttamente inviando una richiesta dal tuo sistema esterno e confermando che gli indirizzi email degli utenti vengano restituiti correttamente.

Recuperare l'URL del web trigger

1. Nella pagina Apps administration (Amministrazione app), individua la sezione Webtrigger URL (URL webtrigger), che mostra l' URL univoco specifico per il tuo sito Jira e l'installazione di questa app:
   • Il tuo sistema esterno deve chiamare questo URL per richiedere le email degli utenti.
   • Esempio di URL: https://YOUR_INSTANCE_ID.hello.atlassian-dev.net/x1/WEBTRIGGER_ID, dove YOUR_INSTANCE_ID è l'identificatore dell'istanza Jira Cloud e WEBTRIGGER_ID è l'identificatore unico dell'endpoint webtrigger generato per la tua app.
2. Fai clic sul pulsante Copy URL (Copia URL) o copia l'intero URL.

Configura il sistema esterno

• Configura il tuo sistema esterno che deve recuperare le email degli utenti Jira con la chiave API e l'URL del webtrigger ottenuti nei passaggi precedenti.

• Endpoint URL: l'URL del web trigger che hai copiato.

• Metodo HTTP: POST

• Intestazioni obbligatorie:

  • Tipo di contenuti: application/json

  • X-Api-Key: YOUR_API_KEY

    Sostituisci YOUR_API_KEY con la chiave API che hai impostato o generato nella sezione Configurare la chiave API.

Comando curl di esempio

Questo esempio mostra la chiamata al web trigger User Identity Accessor per Jira Cloud, che accetta un array di ID account e restituisce gli indirizzi email.

curl --location --request POST 'https://YOUR_INSTANCE_ID.hello.atlassian-dev.net/x1/ENDPOINT_PATH' \
--header 'X-Api-Key: YOUR-API-KEY' \
--header 'Content-Type: application/json' \
--data-raw '{
   "accountIds": [
       "ACCOUNT_ID_1",
       "ACCOUNT_ID_2"
   ]
}'

Sostituisci:

• YOUR_INSTANCE_ID con l'ID istanza Jira Cloud
• ENDPOINT_PATH con il percorso dell'endpoint API
• YOUR_API_KEY con la chiave API che hai impostato o generato nella sezione Configura la chiave API
• ACCOUNT_ID con gli ID account Atlassian che desideri come target

Risposta prevista

[{"accountId":"ACCOUNT_ID_1","emailAddress":"EMAIL_ADDRESS_1"},
 {"accountId":"ACCOUNT_ID_2","emailAddress":"EMAIL_ADDRESS_2"}]

Sostituisci:

• ACCOUNT_ID_X con gli ID account Atlassian effettivi
• USER_EMAIL_X con gli indirizzi email degli utenti restituiti dalla chiamata API

Implementa le best practice per la sicurezza

Per confermare la sicurezza della tua chiave API, segui questi suggerimenti:

• Memorizza la chiave API in modo sicuro nella configurazione del connettore Jira Cloud.
• Verifica che tutte le comunicazioni con l'URL webhook avvengano tramite HTTPS. Questo è il valore predefinito per i web trigger User Identity Accessor per Jira Cloud.

Supporto per User Identity Accessor per Jira Cloud

Le offerte di assistenza sono disponibili a partire da Google per l'app User Identity Accessor per Jira Cloud, che può includere la manutenzione e aggiornamenti regolari per mantenere l'app aggiornata. Se riscontri problemi o hai domande specifiche sulle funzionalità dell'app, contatta l'assistenzaGoogle Cloud . Per saperne di più, consulta Assistenza clienti Google Cloud.