Jira Cloud の構成

公開プレビュー版: 統合検索とアクションの機能は公開プレビュー版です。この機能は、サービス固有規約の一般サービス規約セクションに記載されている「pre-GA サービス規約」の対象となります。pre-GA の機能は「現状のまま」で提供されるものであり、サポートが制限されることがあります。詳細については、リリース ステージの説明をご覧ください。

このページでは、Jira Cloud データストアを作成する前にサードパーティの構成を設定する方法について説明します。

認証と権限を設定する

Atlassian 管理者アカウント センターで認証と権限を設定する必要があります。これは、コネクタがデータにアクセスして同期できるようにするために不可欠です。Jira Cloud コネクタは、OAuth クライアント認証情報や API トークンなど、さまざまな認証方法をサポートしています。

OAuth 2.0 アプリを作成する

認証用の OAuth 2.0 アプリを作成するには、次の手順に沿って Atlassian Developer Console でアプリケーションを設定し、必要なクライアント ID とクライアント シークレットを取得します。

Jira 組織管理者のアクセス権を確認する

Jira 組織管理者のアクセス権を確認する手順は次のとおりです。

1. ユーザー認証情報を使用して Atlassian にログインします。

2. [Jira] アプリを選択します。

3. [設定] をクリックします。

   [Jira settings] に [System] オプションが表示されている場合は、Jira 組織管理者のアクセス権があります。それ以外の場合は、Jira 組織管理者にアクセス権の付与をリクエストしてください。

OAuth 2.0 アプリを作成する

OAuth 2.0 アプリを作成するには、次の操作を行います。

1. Atlassian Developer Console にログインします。

2. プロフィール アイコンをクリックし、[Developer console] を選択します。

3. [Console] ページで、[Create] をクリックし、[OAuth 2.0 Integration] を選択します。

4. アプリの作成ページで、次の操作を行います。

   1. アプリの名前を入力します。

   2. チェックボックスをオンにして、Atlassian のデベロッパー利用規約に同意します。

   3. [作成] をクリックします。

5. アプリのページで、次の操作を行います。

   1. ナビゲーション メニューで [承認] をクリックします。

   2. [Authorization type] テーブルで、[OAuth 2.0（3LO）] の [Add] を選択します。

6. [コールバック URL] フィールドに「https://vertexaisearch.cloud.google.com/console/oauth/jira_oauth.html」と入力します。

7. [変更を保存] をクリックします。

クライアント ID とクライアント シークレットを取得する

クライアント ID とクライアント シークレットを取得するには、次の操作を行います。

1. アプリのページで、ナビゲーション メニューから [配布] をクリックします。

2. [配布] ページで、次の操作を行います。

   1. [配信の制御] セクションで、[編集] を選択します。
   2. [配信ステータス] セクションで、[共有] を選択して、他のフィールドの編集を有効にします。
   3. 次の必須項目に情報を入力します。
      1. [Vendor] に「Google」と入力します。
      2. [Privacy policy] に「https://policies.google.com」と入力します。
      3. [アプリに個人データを保存しますか？] で、[はい] を選択します。
      4. [I confirm that I've implemented the personal data reporting API] チェックボックスをオンにします。詳しくは、Personal Data Reporting API をご覧ください。
   4. [変更を保存] をクリックします。

3. アプリのページで、次の操作を行います。

   1. ナビゲーション メニューで [設定] をクリックします。
   2. 設定ページで、クライアント ID とクライアント シークレットをコピーします。

インスタンス ID とインスタンス URL を取得する

1. 次の手順でインスタンス ID を取得します。

   1. 新しいタブを開き、インスタンスの URL をコピーして、インスタンスの URL に /_edge/tenant_info を追加します。例: https://YOUR_INSTANCE.atlassian.net/_edge/tenant_info
   2. リンクに移動して cloudId の値を見つけます。cloudId がインスタンス ID です。

2. 次の手順でインスタンスの URL を取得します。

   1. atlassian.net に移動し、管理者アカウントでログインします。
   2. 同期するアプリを選択します。たとえば、最初のアプリを同期します。
   3. インスタンスの URL（アドレスバーのサブドメイン）を確認します。

管理者ロールを付与する

Google Cloud コンソールで Jira 管理者にディスカバリー エンジン編集者のロールを付与するには、次の操作を行います。

1. Google Cloud コンソールで、[Gemini Enterprise] ページに移動します。

2. IAM に移動します。

   IAM に移動

3. Jira で管理者のアクセス権を持つユーザー アカウントを見つけて、編集アイコン をクリックします。

4. 管理者にディスカバリー エンジン編集者のロールを付与します。

Atlassian でユーザーに管理者ロールを付与するには、次の操作を行います。

1. 組織管理者アカウントを使用して Atlassian にログインします。

2. メニュー アイコンをクリックして、組織を選択します。または、admin.atlassian.com に移動します。

3. [Admin] ページでプロダクトをクリックし、[Manage users] ボタンを選択します。

   

   ユーザーの管理

4. [User management] で [Groups] をクリックします。

5. [Groups] ページで、次の操作を行います。

   1. [Create group] をクリックします。
   2. グループの名前を入力します。

   

   グループの作成

このグループに、コネクタに必要な権限が付与されます。このグループに追加されたユーザーは、これらの権限を継承します。コネクタはこのグループを使用して認証を行い、ドキュメントを取得します。

1. [Group] ページで、[Add product] をクリックします。

2. Jira のロールとして [User access admin] を選択します。

3. Jira 管理のロールとして [Product admin] を選択します。

   

   Jira ユーザー アクセス管理者

4. [アクセス権を付与] をクリックします。

5. [Add group members] をクリックして、コネクタが認証と必要なリソースへのアクセスに使用するユーザー アカウントまたはグループ メンバーを追加します。

   

   グループ メンバーの追加

ユーザーの可視性を管理する

ユーザーのメールアドレスを Atlassian アカウントのすべてのユーザーに表示する手順は次のとおりです。

1. Atlassian Developer Console にログインします。

2. プロフィール アイコンをクリックし、[Developer console] を選択します。

3. ユーザー プロフィール アイコンをクリックし、[Manage account] を選択します。

   

   アカウントの管理

4. [Profile and visibility] に移動します。

   

   プロフィールと可視性

5. [Contact] に移動し、[Who can see this] を [Anyone] に設定します。

   

   連絡先

ユーザーのメールアドレスを Jira のすべてのユーザーに表示するには、次の操作を行います。

1. ユーザー認証情報を使用して Atlassian にログインします。

2. Jira アプリを選択します。

3. [Settings] > [System] をクリックします。

4. 左側のペインで [General Configuration] を選択します。

5. [Edit Settings] をクリックします。

6. [User email visibility] で、[Public] を選択します。

   

   メールアドレスの可視性の選択

7. [更新] をクリックします。

最小アプリケーション スコープを構成する

定義されたアクションを実行するには、Atlassian プラットフォームで Jira Cloud コネクタに対して次の権限を設定する必要があります。

1. アプリケーション ページで、[Permissions] をクリックします。

2. Jira API に移動し、[Add] をクリックします。

   注: Jira API を追加した後、[Configure] ボタンが表示されるまでに時間がかかることがあります。すぐに表示されない場合は、ページを更新するか、数秒待ってみてください。

3. [構成] をクリックします。

4. [Classic scopes] タブに移動します。

5. [Edit scopes] をクリックし、次の表から要件に応じてクラシック スコープを選択します。

接続モード	権限	目的
連携検索とアクション	read:jira-user、read:jira-work	検索結果とユーザーの詳細をリアルタイムで取得して表示するために必要です。
	write:jira-work	アシスタントが作業項目を変更（問題フィールドの更新など）したり、コメントや問題を管理したりできるようにします。
連携検索のみ	read:jira-user、read:jira-work	問題、プロジェクト、ユーザー プロフィールを検索して表示するために必要です。
データの取り込みとアクション	read:jira-work	ワークアイテムの広範なデータクロールとインデックス登録に必要です。
	write:jira-work	取り込まれた環境内の作業項目に対して書き込みアクション（作成、更新、コメント）を実行するために必要です。
データの取り込み	read:jira-work	検索で利用できるように Jira コンテンツをクロールしてインデックスに登録するために必要です。

1. すべてのスコープが選択されていることを確認し、[保存] をクリックします。

2. [Granular scopes] タブに移動します。

3. [Edit scopes] をクリックし、次の表から要件に応じて粒度の細かいスコープを選択します。

接続モード	権限	目的
連携検索とアクション	write:comment:jira	アシスタントが検索インターフェースから直接新しいコメントや返信を投稿できるようにします。
	write:issue:jira	新しい問題を登録したり、既存の問題を大幅に編集したりする場合に必要です。
データの取り込みとアクション	read:user:jira、read:group:jira、read:avatar:jira	ユーザー/グループのメタデータの同期とユーザー プロファイルの表示に必要です。
	read:issue-security-level:jira、read:issue-security-scheme:jira	アクセス制御に不可欠。取り込まれたデータが Jira のセキュリティ境界を尊重することを保証します。
	read:audit-log:jira	変更を追跡し、増分同期を実行して、取り込まれたデータを最新の状態に保つために使用されます。
	write:comment:jira	アシスタントを使用して問題にコメントを追加するために必要です。
	write:issue:jira	問題の作成または変更を有効にします。
データの取り込み	read:user:jira、read:group:jira、read:avatar:jira	Jira のコンテンツとユーザーの関係をクロールしてインデックスに登録するために必要です。
	read:issue-security-level:jira、read:issue-security-scheme:jira	取り込まれたデータを承認されたユーザーのみが検索できるように、権限をマッピングする必要があります。
	read:audit-log:jira	同期エンジンが更新または削除されたアイテムを特定するために必要です。

1. すべてのスコープが選択されていることを確認し、[保存] をクリックします。

注: アクションをスキップして検索にデータストアを使用する場合は、権限を read 権限のみに制限できます。write 権限は、サポートされているアクションで説明されているアクションを実行する場合にのみ必要です。

User Identity Accessor をインストールする

Jira Cloud サイトに User Identity Accessor for Jira Cloud アプリをインストールする手順は次のとおりです。

1. Atlassian Developer Console に移動します。

2. [メールアドレスの読み取り] と [アプリ ストレージのスコープ] の権限を確認し、[アプリを入手] をクリックします。

   

   権限を確認してアプリを取得する

3. [Select a site to install this app on] リストから、アプリをインストールする Jira サイトを選択します。このリストには、管理者権限を持つサイトのみが表示されます。

   注: アプリをインストールするには、少なくとも 1 つの Jira サイトの管理者である必要があります。

4. [Install] をクリックして、アプリのインストールを完了します。

User Identity Accessor を構成する

User Identity Accessor for Jira Cloud アプリをインストールしたら、外部システム（Jira Cloud コネクタなど）がアプリのウェブトリガーを安全に呼び出してメールアドレスを取得するために使用する API キーを構成します。

構成ページにアクセスする

User Identity Accessor for Jira Cloud アプリの構成ページにアクセスする手順は次のとおりです。

1. Jira Cloud インスタンスで、ナビゲーション メニューの設定アイコン ⚙️ をクリックします。
2. メニューから [Apps] を選択します。
3. [Apps administration] ページで、[Manage apps] リストからアプリ [User Identity Accessor for Jira Cloud] を見つけます。

4. [Configure] をクリックするか、アプリに関連付けられているリンクをクリックします。Jira Cloud 内にアプリ専用の構成ページが開きます。

   

   User Identity Accessor for Jira Cloud アプリを構成する

API キーを設定する

構成ページで API キーを設定する手順は次のとおりです。

1. [API Key Configuration] セクションで、アプリのウェブトリガーへのリクエストを認証するためのシークレット キーを指定します。リクエストの認証には、次のいずれかの方法を使用できます。

   • 独自のキーを入力: 独自の強力な一意の API キーを [API Key] フィールドに入力するか貼り付けます。大文字、小文字、数字、記号を組み合わせた 20～30 文字以上のキーを使用します。

     

     独自のキーを入力

   • キーを生成する: [Generate New Key] ボタンをクリックします。システムによって、強力なランダムキーが生成され、フィールドに表示されます。

     

     キーの生成

     重要: フィールドに表示された API キーをすぐにコピーしてください。セキュリティ上の理由から、保存後や移動後に完全なキーを再度表示できない場合があります。紛失した場合は、新しいキーを設定または生成する必要があります。

2. [Save API Key] をクリックします。成功メッセージが表示され、キーが安全に保存されたことを確認できます。

注: このセクションで生成または作成した API キーは、コネクタの設定時に [Advanced Options] セクションの [Jira Identity Sync Forge Client Secret] フィールドの値として使用されます。

アプリの構成をテストする

User Identity Accessor for Jira Cloud アプリが正しく構成されていることを検証するために、外部システムからリクエストを送信して、ユーザーのメールアドレスが正常に返されることを確認します。

ウェブトリガー URL を取得する

1. [Apps administration] ページで、[Webtrigger URL] セクションを見つけます。このセクションには、Jira サイトとこのアプリのインストールに固有の URL が表示されます。
   • 外部システムは、この URL を呼び出してユーザーのメールアドレスをリクエストする必要があります。
   • URL の例: https://YOUR_INSTANCE_ID.hello.atlassian-dev.net/x1/WEBTRIGGER_ID。ここで、YOUR_INSTANCE_ID は Jira Cloud インスタンスの識別子、WEBTRIGGER_ID はアプリ用に生成されたウェブトリガー エンドポイントの一意の識別子です。
2. [Copy URL] ボタンをクリックするか、URL 全体をコピーします。

外部システムを構成する

• 前述の手順で取得した API キーとウェブトリガー URL を使用して、Jira ユーザーのメールアドレスを取得する必要がある外部システムを構成します。

• エンドポイント URL: コピーしたウェブトリガー URL。

• HTTP メソッド: POST

• 必須ヘッダー:

  • Content-Type: application/json

  • X-Api-Key: YOUR_API_KEY

    YOUR_API_KEY は、API キーを設定するセクションで設定または生成した API キーに置き替えます。

curl コマンドの例

この例では、アカウント ID の配列を受け取り、メールアドレスを返す User Identity Accessor for Jira Cloud ウェブトリガーを呼び出す方法を示します。

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"
   ]
}'

次のように置き換えます。

• YOUR_INSTANCE_ID: Jira Cloud インスタンス ID
• ENDPOINT_PATH: API エンドポイント パス
• YOUR_API_KEY: API キーを設定するセクションで設定または生成した API キー
• ACCOUNT_ID: ターゲットにする Atlassian アカウント ID

想定されるレスポンス

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

次のように置き換えます。

• ACCOUNT_ID_X: 実際の Atlassian アカウント ID
• USER_EMAIL_X: API 呼び出しから返されたユーザーのメールアドレス

セキュリティのベスト プラクティスを実装する

API キーの安全性を確認するには、次の推奨事項に従ってください。

• API キーを Jira Cloud コネクタの構成内に安全に保存します。
• Webhook URL とのすべての通信が HTTPS 経由で行われることを確認します。これは、User Identity Accessor for Jira Cloud ウェブトリガーのデフォルトです。

User Identity Accessor for Jira Cloud のサポート

Google では、User Identity Accessor for Jira Cloud アプリのサポートを提供しています。このサポートには、アプリを最新の状態に保つためのメンテナンスや定期的な更新が含まれます。問題が発生した場合や、アプリの機能についてご不明な点がある場合は、Google Cloud サポートにお問い合わせください。詳細については、Cloud カスタマーケアの利用をご覧ください。