Cmdlets for Microsoft Office 365

Build 23.0.8839

接続の確立

CData Cmdlets ユーザーは、データモジュールをインストールし、接続プロパティを設定してスクリプトを開始できます。このセクションでは、CSV インポートおよびエクスポートcmdlet などのネイティブPowerShell cmdlet でOffice365 Cmdlets を使用する例を示します。

インストールおよび接続

PSGet がある場合は、PowerShell Gallery から次のコマンドを使ってcmdlet をインストールできます。CData サイトからセットアップを取得することもできます。 

Install-Module Office365Cmdlets

プロファイルに以下を追加すると、次のセッションでcmdlet がロードされます。 

Import-Module Office365Cmdlets;

Connect-Office365 cmdlet を使って、別のcmdlet に渡すことができる接続オブジェクトを作成します。 

$conn = Connect-Office365 -OAuthClientId 'MyApplicationId' -OAuthClientSecret 'MySecretKey' -CallbackURL 'http://localhost:33333'

Microsoft Office 365 への認証

Microsoft Office 365 はOAuth 認証標準を利用しています。OAuth を使って認証するには、アプリケーションを作成してOAuthClientId、OAuthClientSecret、およびCallbackURL 接続プロパティを取得する必要があります。

Azure AD

Azure AD は、Microsoft のマルチテナント、クラウドベースのディレクトリおよびID 管理サービスです。これはユーザーベースの認証で、AuthScheme をAzureAD に設定する必要があります。

デスクトップアプリケーション

CData は、デスクトップでの認証を簡単にする埋め込みOAuth アプリケーションを提供します。

接続の前に、以下の変数を設定します。

  • InitiateOAuth：GETANDREFRESH。OAuthAccessToken を自動的に取得およびリフレッシュするために使用します。 CData は、デスクトップでの認証を簡単にする埋め込みOAuth アプリケーションを提供します。例えば、ユーザーがインターネットに接続されていないローカルサーバーを使用しているような場合に利用できます。

    また、Microsoft Office 365 コンソールで設定および登録するカスタムOAuth アプリケーションを介してデスクトップから認証することもできます。詳しくは、カスタムOAuth アプリケーションの作成 を参照してください。

  • カスタムAzure AD アプリケーションのみ：
    • OAuthClientId：カスタムOAuth アプリケーションの登録時に割り当てられたクライアントId。
    • OAuthClientSecret：カスタムOAuth アプリケーションの登録時に割り当てられたクライアントシークレット。
    • CallbackURL：カスタムOAuth アプリケーションの登録時に定義されたリダイレクトURI。

接続すると、本製品 はデフォルトブラウザでMicrosoft Office 365 のOAuth エンドポイントを開きます。ログインして、アプリケーションにアクセス許可を与えます。

アクセストークンの期限が切れたときは、本製品 は自動でアクセストークンをリフレッシュします。

ヘッドレスマシン

ヘッドレスマシンに置かれているリソースにログインする必要がある場合は、インターネットブラウザに対応した別の端末で認証する必要があります。 以下のいずれかの方法で行います。

  • 後述のVerifier code を取得および交換に従い、OAuthVerifier 値を取得します。
  • 別のマシンに本製品 をインストールし、通常のブラウザベースのフローで認証した後でOAuth 認証値を転送します。

いずれかのオプションを実行後、ヘッドレスマシンからアクセストークンを自動的にリフレッシュするようにドライバーを設定します。

Verifier code を取得および交換

Verifier code を取得するには、インターネットブラウザがあるマシンからOAuth 認可URL で認証し、OAuthVerifier 接続プロパティを取得する必要があります。

  1. 以下のオプションから選択します。

    • 埋め込みOAuth アプリケーションを使用する場合は、Microsoft Office 365 OAuth endpoint をクリックし、ブラウザでエンドポイントを開きます。
    • カスタムOAuth アプリケーションを使用する場合は、以下のプロパティを設定して認可URL を作成します。
      • InitiateOAuth：OFF。
      • OAuthClientId：アプリケーションの登録時に割り当てられたクライアントId。
      • OAuthClientSecret：アプリケーションの登録時に割り当てられたクライアントシークレット。
      認可URL が確立されたら、適切なCallbackURL を指定してGetOAuthAuthorizationURL ストアドプロシージャを呼び出します。ストアドプロシージャによって返されたURL をブラウザで開きます。

  2. ログインして、本製品 にアクセス許可を与えます。verifier code を含むコールバックURL にリダイレクトされます。
  3. verifier code の値を保存します。後ほどこれをOAuthVerifier 接続プロパティに設定します。
次に、OAuth verifier code をOAuth リフレッシュトークンおよびアクセストークンと交換します。

OAuth 認証値を取得するには次のプロパティを設定します。

  • InitiateOAuth：REFRESH。
  • OAuthVerifier：verifier code。
  • OAuthSettingsLocation：ドライバーがOAuth トークン値を保存するファイルの場所。これは接続間で維持されます。
  • カスタムアプリケーションのみ：
    • OAuthClientId：（カスタムアプリのみ）カスタムOAuth アプリケーション設定のクライアントId に設定。
    • OAuthClientSecret：（カスタムアプリのみ）カスタムOAuth アプリケーション設定のクライアントシークレットに設定。

OAuth 設定ファイルが生成されたら、以下のように接続プロパティをリセットします。

  • InitiateOAuth：REFRESH。
  • OAuthSettingsLocation：暗号化されたOAuth 認証値が保存される場所。アクセストークンの自動リフレッシュを有効にするために、この場所が本製品 に読み書きのアクセス許可を与えることを確認してください。
  • カスタムアプリケーションのみ：
    • OAuthClientId：アプリケーションの登録時に割り当てられたクライアントId。
    • OAuthClientSecret：アプリケーションの登録時に割り当てられたクライアントシークレット。

OAuth 設定を転送

ヘッドレスマシンでの接続に先立ち、インターネットブラウザに対応したデバイスでドライバーとの接続を作成し、インストールする必要があります。上述の「デスクトップアプリケーション」の説明に従って、接続プロパティを設定します。

「デスクトップアプリケーション」の手順が完了すると、生成された認証値は、OAuthSettingsLocation で指定された場所に暗号化されて書き込まれます。デフォルトのファイル名はOAuthSettings.txt です。

接続が正常にテストされたら、OAuth 設定ファイルをヘッドレスマシンにコピーします。

ヘッドレスマシンで、次の接続プロパティを設定し、データに接続します。

  • InitiateOAuth：REFRESH。
  • OAuthSettingsLocation：OAuth 設定ファイルの場所。アクセストークンの自動リフレッシュを有効にするために、この場所が本製品 に読み書きのアクセス許可を与えることを確認してください。
  • カスタムアプリケーションのみ：
    • OAuthClientId：アプリケーションの登録時に割り当てられたクライアントId。
    • OAuthClientSecret：アプリケーションの登録時に割り当てられたクライアントシークレット。

Azure サービスプリンシパル

Azure サービスプリンシパルは、ロールに基づいたアプリケーションベースの認証です。これは、認証がユーザーごとではなく、アプリケーションごとに行われることを意味します。 アプリケーションで実行されるすべてのタスクは、デフォルトユーザーコンテキストなしで、割り当てられたロールに基づいて実行されます。 リソースへのアプリケーションのアクセスは、割り当てられたロールの権限によって制御されます。

Azure サービスプリンシパル認証の設定方法については、カスタムOAuth アプリケーションの作成 を参照してください。

Managed Service Identity (MSI)

Azure VM 上でMicrosoft Office 365 を実行しており、MSI を利用して接続したい場合は、AuthScheme をAzureMSI に設定します。

User-Managed Identities

マネージドID のトークンを取得するには、OAuthClientId プロパティを使用してマネージドID の"client_id" を指定します。

VM に複数のユーザーが割り当てられたマネージドID がある場合は、OAuthClientId も指定する必要があります。

データの取得

Select-Office365 cmdlet はデータを取得するためのネイティブなPowerShell インターフェースを提供します。 

$results = Select-Office365 -Connection $conn -Table "Events" -Columns @("Id, location_displayName") -Where "Id='Jq74mCczmFXk1tC10GB'"
Invoke-Office365 cmdlet はSQL インターフェースを提供します。このcmdlet を使うと、Query パラメータを介してSQL クエリを実行できます。

cmdlet 出力のパイプ処理

cmdlet は行オブジェクトをパイプラインに一度に一行ずつ返します。以下は、結果をCSV ファイルにエクスポートします。 

Select-Office365 -Connection $conn -Table Events -Where "Id = 'Jq74mCczmFXk1tC10GB'" | Select -Property * -ExcludeProperty Connection,Table,Columns | Export-Csv -Path c:\myEventsData.csv -NoTypeInformation

Select-Office365 からの結果をSelect-Object cmdlet にパイプして、Export-CSV cmdlet にパイプする前にいくつかのプロパティを実行していることがわかるでしょう。これをする理由は、CData Cmdlets は接続、テーブル、およびカラムの情報を結果セットの各行オブジェクトに追加しますが、必ずしもその情報がCSV ファイルに必要ではないからです。

ただし、これによってcmdlet の出力を別のcmdlet にパイプすることが容易になります。以下に、結果セットをJSON に変換する例を示します。 

 
PS C:\> $conn  = Connect-Office365 -OAuthClientId 'MyApplicationId' -OAuthClientSecret 'MySecretKey' -CallbackURL 'http://localhost:33333'
PS C:\> $row = Select-Office365 -Connection $conn -Table "Events" -Columns (Id, location_displayName) -Where "Id = 'Jq74mCczmFXk1tC10GB'" | select -first 1
PS C:\> $row | ConvertTo-Json
{
  "Connection":  {

  },
  "Table":  "Events",
  "Columns":  [

  ],
  "Id":  "MyId",
  "location_displayName":  "Mylocation_displayName"
}

データの削除

以下は、抽出条件に合うあらゆるレコードを削除します。 

Select-Office365 -Connection $conn -Table Events -Where "Id = 'Jq74mCczmFXk1tC10GB'" | Remove-Office365

データの変更

cmdlet はデータクレンジング同様、データの変換を容易にします。次の例は、レコードがすでに存在するかどうか、挿入する前に更新が必要かどうかをチェックしてから、CSV ファイルのデータをMicrosoft Office 365 にロードします。 

Import-Csv -Path C:\MyEventsUpdates.csv | %{
  $record = Select-Office365 -Connection $conn -Table Events -Where ("Id = `'"+$_.Id+"`'")
  if($record){
    Update-Office365 -Connection $conn -Table Events -Columns @("Id","location_displayName") -Values @($_.Id, $_.location_displayName) -Where "Id  = `'$_.Id`'"
  }else{
    Add-Office365 -Connection $conn -Table Events -Columns @("Id","location_displayName") -Values @($_.Id, $_.location_displayName)
  }
}

Copyright (c) 2024 CData Software, Inc. - All rights reserved.
Build 23.0.8839