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 8.0 (x64)
- 8 コア、3 GHz
- 16 GB RAM、2 GB のディスク領域
- 443 を介したデータ ソースとインターネットへのネットワーク アクセス
組織のプロキシ サーバーまたはファイアウォールが不明なドメインへの通信をブロックする場合は、次の規則を [許可] リストに追加します。
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 つの方法でアップグレードできます。
インストール セクションに記載されているリンクから Graph コネクタ エージェントを手動でダウンロードしてインストールします。
図に示すように、接続ウィンドウで使用可能な [アップグレード] ボタンをクリックします。
[アップグレード] ボタンは、エージェントが 1.x バージョンから 2.x バージョンにアップグレードすることはできません。 エージェントが 1.x から 2.x バージョンにアップグレードする場合は、次の手順に従います。
インストール セクションに記載されているリンクからインストーラーをダウンロードします。
まだインストールされていない場合は、インストーラーから .NET 8 Desktop ランタイムのインストールが求められます。
エンドポイント *.office.com への通信を許可します。
インストール後、GCA 構成アプリが再起動します。 GCA が登録されていない場合は、サインインして登録に進みます。
GCA が既に登録されている場合、GCA 構成アプリには、次の成功メッセージが表示されます。
エラーが発生した場合は、エラー メッセージで推奨される軽減策の手順に従って、GCA 構成アプリ & 再度開きます。
エラー メッセージに 「エージェントの正常性を判断できません。 エラーが解決しない場合は、サポートにお問い合わせください。GcaHostService (トラブルシューティング セクションで説明されている手順) を再起動し、GCA 構成アプリをもう一度開きます。
GCA Config アプリを閉じて開くか、登録の詳細画面の [編集] ボタンの横にある [正常性チェック] ボタンを使用して、いつでもチェックを実行できます。
エージェントのアプリを作成して構成する
まず、サインインし、アカウントに最低限必要な特権が検索管理者であることに注意してください。 その後、エージェントから認証の詳細の入力を求められます。 手順を使用してアプリを作成し、必要な認証の詳細を生成します。
アプリを作成する
Azure portal に移動し、テナントの管理者資格情報でサインインします。
ナビゲーション ウィンドウから Microsoft Entra ID ->App registrations に移動し、[ 新しい登録] を選択します。
アプリの名前を指定し、[ 登録] を選択します。
アプリケーション (クライアント) ID を書き留めます。
ナビゲーション ウィンドウから API アクセス許可 を開き、[ アクセス許可の追加] を選択します。
[Microsoft Graph] を選択し、[アプリケーションのアクセス許可] を選択します。
次のアクセス許可を検索し、[ アクセス許可の追加] を選択します。
アクセス許可 アクセス許可が必要な場合 ExternalItem.ReadWrite.OwnedBy または ExternalItem.ReadWrite.All 常時 ExternalConnection.ReadWrite.OwnedBy 常時 Directory.Read.All ファイル共有、MS SQL、Oracle SQL コネクタに必要 [ TenantName] の [管理者の同意を付与する] を 選択し、[ はい] を選択して確認します。
アクセス許可が "付与" 状態であることを確認します。
認証を構成する
認証の詳細は、クライアント シークレットまたは証明書を使用して指定できます。 任意の手順に従います。
認証用のクライアント シークレットの構成
Azure portal に移動し、テナントの管理者資格情報でサインインします。
ナビゲーション ウィンドウから [アプリの登録 ] を開き、適切なアプリに移動します。 [ 管理] で、[ 証明書とシークレット] を選択します。
[ 新しいクライアント シークレット ] を選択し、シークレットの有効期限を選択します。 生成されたシークレットをコピーし、再度表示されないため保存します。
このクライアント シークレットとアプリケーション ID を使用して、エージェントを構成します。 英数字を使用できます。 エージェントの [名前] フィールドに空白を使用することはできません。
認証に証明書を使用する
証明書ベースの認証を使用するための 3 つの簡単な手順があります。
- 証明書を作成または取得する
- Azure portal に証明書をアップロードする
- エージェントに証明書を割り当てる
手順 1: 証明書を取得する
スクリプトを使用して自己署名証明書を生成できます。 組織が自己署名証明書を許可しない場合があります。 その場合は、この情報を使用して要件を理解し、組織のポリシーに従って証明書を取得します。
$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 -KeyLength 2048 -KeyAlgorithm RSA -HashAlgorithm SHA256
$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 に証明書をアップロードする
アプリケーションを開き、左側のウィンドウから [証明書とシークレット] セクションに移動します。
[ 証明書のアップロード] を選択し、.cer ファイルをアップロードします。
[アプリの登録] を開き、ナビゲーション ウィンドウから [証明書とシークレット] を選択します。 証明書の拇印をコピーします。
手順 3: エージェントに証明書を割り当てる
サンプル スクリプトを使用して証明書を生成すると、スクリプトで識別された場所に PFX ファイルが保存されます。
証明書 pfx ファイルをエージェント コンピューターにダウンロードします。
pfx ファイルをダブルクリックして、証明書のインストール ダイアログを起動します。
証明書のインストール中に、ストアの場所として [ローカル コンピューター ] を選択します。
証明書をインストールしたら、[スタート] メニューから [コンピューター証明書の管理] を開きます。
[ Personal>Certificates] で、新しくインストールされた証明書を選択します。
証明書を選択して長押し (または右クリック) し、[ すべてのタスク>秘密キーの管理 オプション] を選択します。
[アクセス許可] ダイアログで、[追加] オプションを選択します。 新しいウィンドウが表示されます。 その中の [場所] オプションを選択します。 表示されている場所の中からエージェントがインストールされているコンピューターを選択し、[OK] を選択 します。
[ユーザーの選択] ダイアログで、「 NT Service\GcaHostService」 と書き込み、[OK] を選択 します。 [ 名前の確認 ] ボタンは選択しないでください。
[アクセス許可] ダイアログで [OK] を選択します。 エージェント マシンが、証明書を使用してトークンを生成するようにエージェント用に構成されました。
トラブルシューティング
インストールエラー
インストールエラーが発生した場合は、msiexec /i "< パス to msi >\GcaInstaller.msi" /L*V "< destination path >\install.log" を実行してインストール ログを確認します。 セキュリティ例外が発生していないことを確認します。 一般に、これらの例外は間違ったポリシー設定が原因で発生します。 実行ポリシーはリモート署名されている必要があります。 詳細については、このドキュメントの「インストール」セクションを確認してください。
エラーが解決できない場合は、ログを含む MicrosoftGraphConnectorsFeedback@service.microsoft.com 経由でサポートする電子メールを送信します。
登録エラー
アプリケーションを構成するためのサインインが失敗し、ブラウザー認証が成功した後でも "サインインに失敗しました、もう一度サインイン ボタンを選択してください" というエラーが表示された場合は、services.msc を開き、GcaHostService が実行されているかどうかを確認します。 起動しない場合は、手動で起動します。 タスク マネージャーで、[サービス] タブに移動し、GcaHostService が実行中の状態であるかどうかを確認します。 そうでない場合は、右クリックしてサービスを開始します。
"ログオンエラーが原因でサービスが開始されませんでした" というエラーでサービスを開始できない場合は、仮想アカウント "NT Service\GcaHostService" にマシン上のサービスとしてサインインするためのアクセス許可があるかどうかを確認します。 手順については、このリンクを参照してください。 ローカル ポリシー\ユーザー権利の割り当てでユーザーまたはグループを追加するオプションがグレー表示されている場合は、このアカウントを追加しようとしているユーザーにこのマシンに対する管理者特権がないか、グループ ポリシーがオーバーライドされていることを意味します。 ホスト サービスがサービスとしてログオンできるようにするには、グループ ポリシーを更新する必要があります。
登録後のエラー
登録後、一部のローカル設定がエージェントの接続に影響する可能性があります。
エージェントがオフラインである
Graph コネクタ サービスに接続できない場合、エージェントはオフラインと見なされます。 このような場合は、次の手順に従います。
エージェントが実行されているかどうかを確認する - エージェントがインストールされているマシンにサインインし、実行されているかどうかを確認します。 タスク マネージャーで、[サービス] タブに移動し、GcaHostService が実行中の状態であるかどうかを確認します。 そうでない場合は、右クリックしてサービスを開始します。
ドメイン 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 ではない場合は、プロキシ/ファイアウォールでドメインが許可され、要求がプロキシを経由していることを確認します。
手順が正常に完了し、エージェントがまだオフラインの場合は、ネットワーク プロキシの問題がないか GCA ログを確認します。
- GcaHostService ログは、指定された場所にあります (このパスに手動で移動する必要がある場合があります。エクスプローラーで貼り付けをコピーできない場合があります)。
- Windows Server 2016 OS の場合: C:\Users\GcaHostService\AppData\Local\Microsoft\GraphConnectorAgent\HostService\logs
- サポートされているその他のすべての Windows OS バージョン: C:\Windows\ServiceProfiles\GcaHostService\AppData\Local\Microsoft\GraphConnectorAgent\HostService\logs
- フォルダー内のログ ファイルを "変更時刻" の逆の順序で並べ替え、最新の 2 つのファイルを開きます。
- "ターゲット コンピューターがアクティブに拒否したため、接続できませんでした" というテキストが表示されたエラー メッセージがないか確認します。
- これは、GcaHostService 仮想アカウントが https://gcs.office.com エンドポイントに接続できないネットワーク設定に問題があることを示します。
- ネットワーク/プロキシ チームに問い合わせて、仮想アカウント (NT Service\GcaHostService) がこのドメインにトラフィックを送信することを許可します。
- ログ ファイルにこれらのエラーが含まれている場合は、問題が解決されたことを確認できます。
- GcaHostService ログは、指定された場所にあります (このパスに手動で移動する必要がある場合があります。エクスプローラーで貼り付けをコピーできない場合があります)。
いずれの手順でも問題が解決しない場合は、 MicrosoftGraphConnectorsFeedback@service.microsoft.comに電子メールを送信してサポートに問い合わせ、前述の場所から 2 つの最新のログ ファイルを指定します。
エージェントに到達できない
エージェントに到達できない場合に接続を設定すると、次の画面が表示されます。
エラーの詳細に記載されている Service Bus 名前空間を使用して、次の手順に従ってトラブルシューティングを行います。
PowerShell から、次のコマンドを実行します。
tnc <yournamespacename>.servicebus.windows.net -port 443
応答には、出力 "TcpTestSucceeded: True" が含まれている必要があります。
false の場合は、プロキシ/ファイアウォールでドメインが許可され、要求がプロキシを経由していることを確認します。
ICMP Ping がネットワークでブロックされているために tnc を実行できない場合は、PowerShell で次のコマンドを実行します。
wget https://<yournamespacename>.servicebus.windows.net/
出力には"StatusCode: 200" が含まれている必要があります。
false の場合は、プロキシ/ファイアウォールでドメインが許可され、要求がプロキシを経由していることを確認します。
いずれの手順でも問題が解決しない場合は、 MicrosoftGraphConnectorsFeedback@service.microsoft.comに電子メールを送信してサポートに問い合わせ、前述の場所から 2 つの最新のログ ファイルを指定します。
進行中の更新
このエラーは、更新が既に進行中で、最大 30 分後にエラーが消える場合に表示されます。
エラーが 30 分後に続く場合は、次の手順に従います。
エージェントが実行されているかどうかを確認する - エージェントがインストールされているマシンにサインインし、実行されているかどうかを確認します。 タスク マネージャーで、[サービス] タブに移動し、GcaHostService が実行中の状態であるかどうかを確認します。 そうでない場合は、右クリックしてサービスを開始します。
それでも問題が解決しない場合は、 MicrosoftGraphConnectorsFeedback@service.microsoft.comに電子メールを送信してサポートに問い合わせ、2 つの最新のログ ファイルを指定します。 ログにアクセスする場所に手動で移動し、チームと同じものを共有する - C:\Windows\System32\config\systemprofile\AppData\Local\Microsoft\GraphConnectorAgent\AgentUpdateApp\logs
接続エラー
接続の作成中に "接続のテスト" アクションが失敗し、指定されたユーザー名とパスワードが正しい場合でも、"ユーザー名/パスワードとデータ ソース パスを確認してください" というエラーが表示される場合は、コネクタ エージェントがインストールされているマシンに対して対話型サインイン権限がユーザー アカウントに付与されていることを確認します。 ログオン ポリシー管理に関するドキュメントを確認して、サインイン権限を確認できます。 また、データ ソースとエージェント マシンが同じネットワーク上にあることを確認します。