Microsoft Graph コネクタ エージェント

オンプレミス コネクタを使用するには、 Microsoft Graph コネクタ エージェント ソフトウェアをインストールする必要があります。 これにより、オンプレミスのデータとコネクタ API 間の安全なデータ転送が可能になります。 この記事では、エージェントのインストールと構成について説明します。

インストール

最新バージョンの Microsoft Graph コネクタ エージェントをダウンロードし、インストール構成アシスタントを使用してソフトウェアをインストールします。 コネクタ エージェント ソフトウェアのリリース ノートについては、こちらを参照してください。

実行ポリシーの確認

リモート署名付きスクリプトの実行を許可するには、実行ポリシーを設定する必要があります。 マシンまたはグループ レベルのポリシーで同じポリシーが制限されている場合、GCA のインストールは失敗します。 次のコマンドを実行して、実行ポリシーを取得します。

Get-ExecutionPolicy -List

詳細を確認し、適切な実行ポリシーを設定するには、「 実行ポリシー」を参照してください。

推奨される構成

マシンの推奨構成を使用すると、コネクタ エージェント インスタンスは最大 3 つの接続を処理できます。 それ以外の接続では、エージェント上のすべての接続のパフォーマンスが低下する可能性があります。 推奨される構成を次に示します。

• Windows 10、Windows Server 2016 R2 以降のバージョン
• .NET Framework 4.7.2
• .NET Core Desktop Runtime 7.0 (x64)
• 8 コア、3 GHz
• 16 GB RAM、2 GB のディスク領域
• 443 を介したデータ ソースとインターネットへのネットワーク アクセス

organizationのプロキシ サーバーまたはファイアウォールが不明なドメインへの通信をブロックする場合は、次の規則を [許可] リストに追加します。

M365 Enterprise	M365 GCC	M365 GCCH
1. *.servicebus.windows.net	1. *.servicebus.usgovcloudapi.net	1. *.servicebus.usgovcloudapi.net
2. *.events.data.microsoft.com	2. *.events.data.microsoft.com	2. *.events.data.microsoft.com
3. *.office.com	3. *.office.com	3. *.office.com、 *.office365.us
4. https://login.microsoftonline.com	4. https://login.microsoftonline.com	4. https://login.microsoftonline.com、 https://login.microsoftonline.us
5. https://gcs.office.com/	5. https://gcsgcc.office.com	5. https://gcs.office365.us/
6. https://graph.microsoft.com/	6. https://graph.microsoft.com	6. https://graph.microsoft.com/、 https://graph.microsoft.us/

注:

プロキシ認証はサポートされていません。 環境に認証が必要なプロキシがある場合は、コネクタ エージェントにプロキシのバイパスを許可することをお勧めします。

アップグレード

Graph コネクタ エージェントは、次の 2 つの方法でアップグレードできます。

1. インストール セクションに記載されているリンクから Graph コネクタ エージェントを手動でダウンロードしてインストールします。

2. 図に示すように、接続ウィンドウで使用可能な [アップグレード] ボタンをクリックします。接続

[アップグレード] ボタンは、エージェントが 1.x バージョンから 2.x バージョンにアップグレードすることはできません。 エージェントが 1.x から 2.x バージョンにアップグレードする場合は、次の手順に従います。

1. インストール セクションに記載されているリンクからインストーラーをダウンロードします。

2. まだインストールされていない場合は、インストーラーから .NET 7 Desktop ランタイムのインストールが求められます。

3. エンドポイント *.office.com への通信を許可します。

4. インストール後、GCA 構成アプリが再起動します。 GCA が登録されていない場合は、サインインして登録に進みます。

5. GCA が既に登録されている場合、GCA 構成アプリには、次の成功メッセージが表示されます。

6. エラーが発生した場合は、エラー メッセージで推奨される軽減策の手順に従って、GCA 構成アプリ & 再度開きます。

7. エラー メッセージに 「エージェントの正常性を判断できません。 エラーが解決しない場合は、サポートにお問い合わせください。GcaHostService (トラブルシューティング セクションで説明されている手順) を再起動し、GCA 構成アプリをもう一度開きます。

8. GCA Config アプリを閉じて開くか、登録の詳細画面の [編集] ボタンの横にある [正常性チェック] ボタンを使用して、いつでもチェックを実行できます。

エージェントのアプリを作成して構成する

まず、サインインし、アカウントに最低限必要な特権が検索管理者であることに注意してください。 その後、エージェントから認証の詳細の入力を求められます。 手順を使用してアプリを作成し、必要な認証の詳細を生成します。

アプリを作成する

1. Azure portalに移動し、テナントの管理者資格情報でサインインします。

2. ナビゲーション ウィンドウから Microsoft Entra ID ->アプリの登録 に移動し、[新しい登録] を選択します。

3. アプリの名前を指定し、[ 登録] を選択します。

4. アプリケーション (クライアント) ID を書き留めます。

5. ナビゲーション ウィンドウから API アクセス許可 を開き、[ アクセス許可の追加] を選択します。

6. [Microsoft Graph] を選択し、[アプリケーションのアクセス許可] を選択します。

7. 次のアクセス許可をSearchし、[アクセス許可の追加] を選択します。

   アクセス許可	アクセス許可が必要な場合
   ExternalItem.ReadWrite.OwnedBy または ExternalItem.ReadWrite.All	常時
   ExternalConnection.ReadWrite.OwnedBy	常時
   Directory.Read.All	ファイル共有、MS SQL、Oracle SQL コネクタに必要

8. [ TenantName] の [管理者の同意を付与する] を 選択し、[ はい] を選択して確認します。

9. アクセス許可が "付与" 状態であることを確認します。

   

認証を構成する

認証の詳細は、クライアント シークレットまたは証明書を使用して指定できます。 任意の手順に従います。

認証用のクライアント シークレットの構成

1. Azure portalに移動し、テナントの管理者資格情報でサインインします。

2. ナビゲーション ウィンドウから [アプリの登録 ] を開き、適切なアプリに移動します。 [ 管理] で、[ 証明書とシークレット] を選択します。

3. [ 新しいクライアント シークレット ] を選択し、シークレットの有効期限を選択します。 生成されたシークレットをコピーし、再度表示されないため保存します。

4. このクライアント シークレットとアプリケーション ID を使用して、エージェントを構成します。 英数字を使用できます。 エージェントの [名前] フィールドに空白を使用することはできません。

認証に証明書を使用する

証明書ベースの認証を使用するための 3 つの簡単な手順があります。

1. 証明書を作成または取得する
2. 証明書をAzure portalにアップロードする
3. エージェントに証明書を割り当てる

手順 1: 証明書を取得する

スクリプトを使用して自己署名証明書を生成できます。 organizationで自己署名証明書が許可されない場合があります。 その場合は、この情報を使用して要件を理解し、organizationのポリシーに従って証明書を取得します。

$dnsName = "<TenantDomain like agent.onmicrosoft.com>" # Your DNS name
$password = "<password>" # Certificate password
$folderPath = "D:\New folder\" # Where do you want the files to get saved to? The folder needs to exist.
$fileName = "agentcert" # What do you want to call the cert files? without the file extension
$yearsValid = 10 # Number of years until you need to renew the certificate
$certStoreLocation = "cert:\LocalMachine\My"
$expirationDate = (Get-Date).AddYears($yearsValid)
$certificate = New-SelfSignedCertificate -DnsName $dnsName -CertStoreLocation $certStoreLocation -NotAfter $expirationDate -KeyExportPolicy Exportable -KeySpec Signature
$certificatePath = $certStoreLocation + '\' + $certificate.Thumbprint
$filePath = $folderPath + '\' + $fileName
$securePassword = ConvertTo-SecureString -String $password -Force -AsPlainText
Export-Certificate -Cert $certificatePath -FilePath ($filePath + '.cer')
Export-PfxCertificate -Cert $certificatePath -FilePath ($filePath + '.pfx') -Password $securePassword

手順 2: 証明書をAzure portalにアップロードする

1. アプリケーションを開き、左側のウィンドウから [証明書とシークレット] セクションに移動します。

2. [ 証明書のアップロード] を選択し、.cer ファイルをアップロードします。

3. [アプリの登録] を開き、ナビゲーション ウィンドウから [証明書とシークレット] を選択します。 証明書の拇印をコピーします。

手順 3: エージェントに証明書を割り当てる

サンプル スクリプトを使用して証明書を生成すると、スクリプトで識別された場所に PFX ファイルが保存されます。

1. 証明書 pfx ファイルをエージェント コンピューターにダウンロードします。

2. pfx ファイルをダブルクリックして、証明書のインストール ダイアログを起動します。

3. 証明書のインストール中に、ストアの場所として [ローカル コンピューター ] を選択します。

4. 証明書をインストールしたら、[スタート] メニューから [コンピューター証明書の管理] を開きます。

5. [個人用証明書] で、新しくインストールされた証明書を>選択します。

6. 証明書を選択して長押し (または右クリック) し、[すべてのタスク>] [秘密キーの管理] オプションを選択します。

7. [アクセス許可] ダイアログで、[追加] オプションを選択します。 新しいウィンドウが表示されます。 その中の [場所] オプションを選択します。 表示されている場所の中からエージェントがインストールされているコンピューターを選択し、[OK] を選択 します。

8. [ユーザーの選択] ダイアログで、「 NT Service\GcaHostService」 と書き込み、[OK] を選択 します。 [ 名前の確認 ] ボタンは選択しないでください。

9. [アクセス許可] ダイアログで [OK] を選択します。 エージェント マシンが、証明書を使用してトークンを生成するようにエージェント用に構成されました。

トラブルシューティング

インストールエラー

インストールエラーが発生した場合は、msiexec /i " path to msi\GcaInstaller.msi"< /L*V "< destination path >\install.log" を実行してインストール ログをチェック>します。 セキュリティ例外が発生していないことを確認します。 一般に、これらの例外は間違ったポリシー設定が原因で発生します。 実行ポリシーはリモート署名されている必要があります。 詳細については、このドキュメントの「インストール」セクションをチェック。

エラーが解決できない場合は、ログを使用して MicrosoftGraphConnectorsFeedback@service.microsoft.com サポートする電子メールを送信します。

登録エラー

アプリケーションを構成するためのサインインが失敗し、ブラウザー認証が成功した後でも "サインインに失敗しました、もう一度サインイン ボタンを選択してください" というエラーが表示された場合は、services.msc を開き、GcaHostService が実行されている場合はチェックします。 起動しない場合は、手動で起動します。 タスク マネージャーで、[サービス] タブに移動し、GcaHostService が実行中の状態の場合にチェックします。 そうでない場合は、右クリックしてサービスを開始します。

仮想アカウント "NT Service\GcaHostService" にマシン上のサービスとしてサインインするためのアクセス許可がある場合に、"ログオンエラーが原因でサービスが開始されませんでした" というエラーでサービスが開始できない場合は、チェックします。 手順については、このリンクを参照してください。 ローカル ポリシー\ユーザー権利の割り当てでユーザーまたはグループを追加するオプションがグレー表示されている場合は、このアカウントを追加しようとしているユーザーにこのマシンに対する管理者特権がないか、グループ ポリシーがオーバーライドされていることを意味します。 ホスト サービスがサービスとしてログオンできるようにするには、グループ ポリシーを更新する必要があります。

登録後のエラー

登録後、一部のローカル設定がエージェントの接続に影響する可能性があります。

エージェントがオフラインである

Graph コネクタ サービスに接続できない場合、エージェントはオフラインと見なされます。 このような場合は、次の手順に従います。

1. エージェントが実行されているかどうかを確認する - エージェントがインストールされているコンピューターにサインインし、実行中の場合はチェックします。 タスク マネージャーで、[サービス] タブに移動し、GcaHostService が実行中の状態の場合にチェックします。 そうでない場合は、右クリックしてサービスを開始します。

   

2. ドメイン gcs.office.com に到達できるかどうかを確認します。 (GCC テナントの場合は、gcsgcc.office.com を置き換え、GCCHigh テナントの場合は、最初の表に示すように gcs.office365.us を置き換えます)。次の手順に従います。

   • PowerShell から、次のコマンドを実行します。

   tnc gcs.office.com -Port 443
   

   応答には、次のように出力 "TcpTestSucceeded: True" が含まれている必要があります。

   

   false の場合は、プロキシ/ファイアウォールでドメインが許可され、要求がプロキシを経由していることを確認します。

   • より具体的なテストを行う場合、または ICMP ping がネットワークでブロックされているために tnc を実行できない場合は、次のコマンドを実行します。

   wget https://gcs.office.com/v1.0/admin/AdminDataSetCrawl/healthcheck
   

   出力には "StatusCode: 200" が含まれている必要があります。

   

   200 ではない場合は、プロキシ/ファイアウォールでドメインが許可され、要求がプロキシを経由していることを確認します。

3. 手順が正常に完了し、エージェントがまだオフラインの場合は、ネットワーク プロキシの問題について GCA ログをチェックします。

   • GcaHostService ログは、指定された場所にあります (このパスに手動で移動する必要がある場合があります。エクスプローラーで貼り付けをコピーできない場合があります)。
     1. Windows Server 2016 OS の場合: C:\Users\GcaHostService\AppData\Local\Microsoft\GraphConnectorAgent\HostService\logs
     2. サポートされているその他のすべての Windows OS バージョン: C:\Windows\ServiceProfiles\GcaHostService\AppData\Local\Microsoft\GraphConnectorAgent\HostService\logs
   • フォルダー内のログ ファイルを "変更時刻" の逆の順序で並べ替え、最新の 2 つのファイルを開きます。
   • "ターゲット コンピューターがアクティブに拒否したため、接続できませんでした" というテキストが表示されたエラー メッセージがないか確認します。
     1. これは、GcaHostService 仮想アカウントがエンドポイントに接続 https://gcs.office.com できないネットワーク設定に問題があることを示します。
     2. ネットワーク/プロキシ チームに問い合わせて、仮想アカウント (NT Service\GcaHostService) がこのドメインにトラフィックを送信することを許可します。
     3. ログ ファイルにこれらのエラーが含まれている場合は、問題が解決されたことを確認できます。

4. いずれの手順でも問題が解決しない場合は、 にメールを送信してサポートに MicrosoftGraphConnectorsFeedback@service.microsoft.com問い合わせ、前述の場所から 2 つの最新のログ ファイルを指定します。

エージェントに到達できない

エージェントに到達できない場合に接続を設定すると、次の画面が表示されます。

エラーの詳細に記載されている Service Bus 名前空間を使用して、次の手順に従ってトラブルシューティングを行います。

1. PowerShell から、次のコマンドを実行します。

   tnc <yournamespacename>.servicebus.windows.net -port 443
   

   応答には、出力 "TcpTestSucceeded: True" が含まれている必要があります。

   

   false の場合は、プロキシ/ファイアウォールでドメインが許可され、要求がプロキシを経由していることを確認します。

2. ICMP Ping がネットワークでブロックされているために tnc を実行できない場合は、PowerShell で次のコマンドを実行します。

   wget https://<yournamespacename>.servicebus.windows.net/
   

   出力には"StatusCode: 200" が含まれている必要があります。

   

   false の場合は、プロキシ/ファイアウォールでドメインが許可され、要求がプロキシを経由していることを確認します。

3. いずれの手順でも問題が解決しない場合は、 にメールを送信してサポートに MicrosoftGraphConnectorsFeedback@service.microsoft.com問い合わせ、前述の場所から 2 つの最新のログ ファイルを指定します。

進行中の更新

このエラーは、更新が既に進行中で、最大 30 分後にエラーが消える場合に表示されます。

エラーが 30 分後に続く場合は、次の手順に従います。

1. エージェントが実行されているかどうかを確認する - エージェントがインストールされているコンピューターにサインインし、実行中の場合はチェックします。 タスク マネージャーで、[サービス] タブに移動し、GcaHostService が実行中の状態の場合にチェックします。 そうでない場合は、右クリックしてサービスを開始します。

2. それでも問題が解決しない場合は、 にメールを送信してサポートに MicrosoftGraphConnectorsFeedback@service.microsoft.com問い合わせ、2 つの最新のログ ファイルを指定します。 ログにアクセスする場所に手動で移動し、チームと同じものを共有する - C:\Windows\System32\config\systemprofile\AppData\Local\Microsoft\GraphConnectorAgent\AgentUpdateApp\logs

接続エラー

接続の作成中に "接続のテスト" アクションが失敗し、指定したユーザー名とパスワードが正しい場合でも、"ユーザー名/パスワードとデータ ソース パスをチェックしてください" というエラーが表示される場合は、コネクタ エージェントがインストールされているマシンに対して対話型サインイン権限がユーザー アカウントに付与されていることを確認します。 ログオン ポリシー管理に関するドキュメントを参照して、サインイン権限をチェックできます。 また、データ ソースとエージェント マシンが同じネットワーク上にあることを確認します。