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

Gmail への接続

本製品 は最新のREST API とIMAP プロトコルを使用したGmail への接続をサポートしています。AuthScheme を使用して接続方法を制御します。REST API がデフォルトです。

Gmail への認証

使用可能な認証スキームは次のとおりです。

• Basic（IMAP のみ）
• OAuth
• OAuthJWT
• GCP インスタンスアカウント

Basic（IMAP のみ）

IMAP を使用する場合は、ドライバーがIMAP プロトコルを介してGmail と通信できるようにIMAP を有効にする必要があります。IMAP を使用すると、すべてのクライアントデバイスで個々のコピーではなく、同じリモートデータを使用できます。以下の手順に従って、IMAP 経由のGmail へのアクセスを有効にします。

1. Gmail Web インターフェースを開き、［設定］ボタン（歯車のアイコン）をクリックします。
2. メール転送とPOP/IMAP タブでIMAP を有効にするを選択します。
3. 変更を保存します。

非推奨のお知らせ 2022年5月30日時点で、Google はユーザー名とパスワードのみでGoogle アカウントにサインインするよう求めるサードパーティ製のアプリやデバイスの使用をサポートしなくなりました。この認証方法をまだ使えるようにする代替案もあります。例えば、App Passwords です。これを考慮して、Basic 認証を非推奨としました。CData では、よりセキュアな認証方法であるOAuth への切り替えをお勧めします。

この認証方法を使うには、AuthScheme をBasic に、Schema をIMAP に設定します。このアプローチは、自分のデータにアクセスする必要がある場合に適しています。User プロパティとPassword プロパティに、有効なGmail ユーザー資格情報を設定します。

ユーザーアカウント（OAuth）

AuthScheme は、すべてのユーザーアカウントフローでOAuth に設定する必要があります。加えて、すべてのユーザーアカウントフローで、Gmail にカスタムアプリケーションを作成し登録する必要があります。それから本製品 を使用してOAuth トークンの値を取得および管理します。カスタムアプリケーションについて詳しくは、カスタムOAuth アプリの作成 を参照してください。

NOTE： CData は、OAuth 認証でIMAP およびREST の両方のスキーマをサポートしています。唯一の違いは、IMAP はUser 接続プロパティを必要とすることです。REST では必要ありません。

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

次の接続プロパティを設定して、接続してください。

• OAuthClientId：カスタムOAuth アプリケーション設定のクライアントId に設定。
• OAuthClientSecret：カスタムOAuth アプリケーション設定のクライアントシークレットに設定。
• User：（IMAP のみ）認証に使用されるGmail ユーザーアカウントに設定。

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

• コールバックURL からアクセストークンを取得します。
• 古いトークンの期限が切れたときは、新しいアクセストークンを取得します。
• OAuth 値をOAuthSettingsLocation に保存します。これらの値は接続間で永続化されます。

Web アプリケーション

OAuth アクセストークンの取得

次の接続プロパティを設定し、OAuthAccessToken を取得します。

• OAuthClientId：アプリケーション設定のクライアントId に設定。
• OAuthClientSecret：アプリケーション設定のクライアントシークレットに設定。
• User：（IMAP のみ）認証に使用されるGmail ユーザーアカウントに設定。

続いてストアドプロシージャを呼び出し、OAuth 交換を完了します。

1. GetOAuthAuthorizationURL ストアドプロシージャを呼び出します。CallbackURL インプットをアプリケーション設定で指定したコールバックURL に設定します。ストアドプロシージャがOAuth エンドポイントのURL を返します。
2. ステップ1でストアドプロシージャが返したURL に移動します。カスタムOAuth アプリケーションにログインして、Web アプリケーションを認可します。認証されると、ブラウザはコールバックURL にリダイレクトします。
3. GetOAuthAccessToken ストアドプロシージャを呼び出します。AuthMode をWEB に、Verifier インプットをコールバックURL のクエリ文字列の"code" パラメータに設定します。

アクセストークンとリフレッシュトークンを取得した後、データに接続し、OAuth アクセストークンを自動または手動でリフレッシュすることが可能です。

OAuth アクセストークンの自動リフレッシュ

ドライバーがOAuth アクセストークンを自動的にリフレッシュするようにするには、最初のデータ接続で次のように設定します。

• InitiateOAuth：REFRESH に設定。
• OAuthClientId：アプリケーション設定のクライアントId に設定。
• OAuthClientSecret：アプリケーション設定のクライアントシークレットに設定。
• OAuthAccessToken：GetOAuthAccessToken によって返されたアクセストークンに設定。
• OAuthRefreshToken：GetOAuthAccessToken によって返されたリフレッシュトークンに設定。
• OAuthSettingsLocation：本製品 がOAuth トークン値を保存する場所に設定。これは接続間で維持されます。
• User：（IMAP のみ）認証に使用されるGmail ユーザーアカウントに設定。

次回のデータ接続では、OAuthAccessToken およびOAuthRefreshToken の値は、OAuthSettingsLocation から取得されます。

OAuth アクセストークンの手動リフレッシュ

データ接続時に手動でOAuth アクセストークンをリフレッシュするために必要な値は、OAuth リフレッシュトークンのみです。

GetOAuthAccessToken によって返されたExpiresIn パラメータ値が経過した後に、RefreshOAuthAccessToken ストアドプロシージャを使用し、手動でOAuthAccessToken をリフレッシュします。次の接続プロパティを設定します。

• OAuthClientId：アプリケーション設定のクライアントId に設定。
• OAuthClientSecret：アプリケーション設定のクライアントシークレットに設定。
• User：（IMAP のみ）認証に使用されるGmail ユーザーアカウントに設定。

次に、RefreshOAuthAccessToken を呼び出し、OAuthRefreshToken にGetOAuthAccessToken によって返されたOAuth リフレッシュトークンを指定します。新しいトークンが取得できたら、OAuthAccessToken プロパティにRefreshOAuthAccessToken によって返された値を設定し、新しい接続をオープンします。

最後に、OAuth リフレッシュトークンを保存し、OAuth アクセストークンの有効期限が切れた後に手動でリフレッシュできるようにします。

ヘッドレスマシン

ヘッドレスマシンのユーザーアカウントでOAuth を使用するようにドライバーを設定するには、インターネットブラウザに対応した別の端末で認証する必要があります。

1. 以下のオプションから選択します。
   • オプション1：後述の「Verifier code を取得および交換」に従い、OAuthVerifier 値を取得します。
   • オプション2：インターネットブラウザに対応したマシンに本製品 をインストールし、後述の「OAuth 設定を転送」の説明に従い、通常のブラウザベースのフローで認証後にOAuth 認証値を転送します。
2. 次に、ヘッドレスマシンからアクセストークンを自動的にリフレッシュするように本製品 を設定します。

オプション1：Verifier code を取得および交換

Verifier code を取得するには、OAuth Authorization URL で認証する必要があります。

インターネットブラウザに対応したマシンから認証してOAuthVerifier 接続プロパティを取得する方法は次のとおりです。

1. 以下のプロパティを設定し、認証URL を作成します。
   • InitiateOAuth：OFF に設定。
   • OAuthClientId：アプリケーションの登録時に割り当てられたクライアントId に設定。
   • OAuthClientSecret：アプリケーションの登録時に割り当てられたクライアントシークレットに設定。
   • User：（IMAP のみ）認証に使用されるGmail ユーザーアカウントに設定。
2. 適切なCallbackURL を指定してGetOAuthAuthorizationURL ストアドプロシージャを呼び出します。ストアドプロシージャによって返されたURL をブラウザで開きます。
3. ログインして、本製品 にアクセス許可を与えます。すると、verifier code を含むコールバックURL にリダイレクトされます。
4. verifier code の値を保存します。後ほどこれをOAuthVerifier 接続プロパティに設定します。

次に、OAuth verifier code をOAuth リフレッシュトークンおよびアクセストークンと交換する必要があります。次のプロパティを設定します。

ヘッドレスマシンでは、次の接続プロパティを設定してOAuth 認証値を取得します。

• InitiateOAuth：REFRESH に設定。
• OAuthVerifier：verifier code に設定。
• OAuthClientId：カスタムOAuth アプリケーション設定のクライアントId に設定。
• OAuthClientSecret：カスタムOAuth アプリケーション設定のクライアントシークレットに設定。
• OAuthSettingsLocation：これを設定すると、暗号化されたOAuth 認証値が指定された場所に永続化されます。
• User：（IMAP のみ）認証に使用されるGmail ユーザーアカウントに設定。

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

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

オプション2：OAuth 設定を転送

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

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

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

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

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

サービスアカウント（OAuthJWT）

サービスアカウントを使用して認証するには、AuthScheme をOAuthJWT に設定します。 このモードにはGoogle Workspace アカウントが必要で、ドメイン全体の委任を通じてユーザーに代わってアクセスできるようにする必要があります。 新しいサービスアカウントを作成し、アカウント証明書のコピーを用意する必要があります。 サービスアカウントを持っていない場合は、カスタムOAuth アプリの作成 の手順に従って作成できます。

NOTE： OAuthJWT 認証方式では、委任が必要です。これは、Google Workspace アカウントを使用している場合のみ可能です。

JSON ファイルの場合は、以下のプロパティを設定します。

• AuthScheme：OAuthJWT に設定。
• OAuthJWTCertType：GOOGLEJSON に設定。
• OAuthJWTCert：Google が提供する.json ファイルへのパスに設定。
• OAuthJWTSubject：（必須） Google Workspace ドメインのユーザーのE メールアドレスに設定。 この値により、サービスアカウントがドメイン全体の委任を通じてユーザーに代わってアクセスできるようになります。これはOAuthJWT でGmail にアクセスするために必要です。 このプロパティがないと、認証は"[400] Precondition check failed" エラーで失敗します。

PFX ファイルの場合は、以下のプロパティを設定します。

• AuthScheme：OAuthJWT に設定。
• OAuthJWTCertType：PFXFILE に設定。
• OAuthJWTCert：Google が提供する.pfx ファイルへのパスに設定。
• OAuthJWTCertPassword：（オプション） .pfx ファイルのパスワードに設定。Google はPFX 証明書を暗号化するため、ほとんどの場合、これを提供する必要があります。
• OAuthJWTCertSubject： （オプション） 複数の証明書を格納するOAuthJWTCertType を使用している場合にのみ設定します。Google によって生成されたPFX 証明書には設定しないでください。
• OAuthJWTIssuer：（オプション） サービスアカウントのE メールアドレスまたはクライアントID に設定。

  Note：Google のOAuthJWT プロトコルには発行者クレームが含まれていますが、本製品 は通常キーストア（PFXFILE）からそれを導出できます。カスタムまたはマルチ証明書PFX ファイル、 または発行者情報が欠落しているファイルを使用している場合、このプロパティを設定します。値は通常、iam.gserviceaccount.com で終わるE メールアドレスです。

• OAuthJWTSubject： （必須） Google Workspace ドメインのユーザーのE メールアドレスに設定。 この値により、サービスアカウントがドメイン全体の委任を通じてユーザーに代わってアクセスできるようになります。これはOAuthJWT でGmail にアクセスするために必要です。 このプロパティがないと、認証は"[400] Precondition check failed" エラーで失敗します。

ドメイン全体の権限の委任要件

OAuthJWT を使用してサービスアカウントでGmail に認証するには、Google でWorkspace 管理コンソールでドメイン全体の委任を適切に設定する必要があります。 この設定は、サービスアカウントがドメイン内のユーザーに代わってアクセスすることを許可するもので、Gmail データにアクセスするための要件です。

• ドメイン全体の委任が必要です：これがないと、Gmail は接続を試みた際に"[400] Precondition check failed" エラーを返します。
• Google Workspace アカウントのみサポートします：個人のGmail アカウント（@gmail.com で終わる）はドメイン全体の委任をサポートしておらず、Gmail API アクセスでサービスアカウントを使用することはできません。
• 各接続は特定のユーザーを偽装する必要があります：OAuthJWTSubject プロパティを使用して、サービスアカウントがアクセスすべきWorkspace ユーザーのメールボックスを指定します。1つの接続につき1人のユーザーのみ偽装できます。
• 変更の適用には時間がかかる場合があります：委任を設定した後、すべてのユーザーに完全に効力を発揮するまで最大24時間かかる場合があります。
• 管理者アクセスが必要です：Google Workspace の特権管理者がサービスアカウントを承認し、適切なOAuth スコープを割り当てる必要があります。

詳しくは、Google Domain-Wide Delegation Guide を参照してください。

GCP インスタンスアカウント

GCP 仮想マシン上で実行している場合は、本製品 は仮想マシンに関連付けられたサービスアカウントを使用して認証できます。 このモードを使用するには、AuthScheme をGCPInstanceAccount に設定します。

接続オブジェクトの作成

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

$conn = Connect-Gmail -User 'MyUser' -Password 'MyPassword'

データの取得

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

$results = Select-Gmail -Connection $conn -Table "Inbox" -Columns @("Id, MessageBody") -Where "From='[email protected]'"

Invoke-Gmail cmdlet はSQL インターフェースを提供します。このcmdlet を使うと、Query パラメータを介してSQL クエリを実行できます。

cmdlet 出力のパイプ処理

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

Select-Gmail -Connection $conn -Table Inbox -Where "From = '[email protected]'" | Select -Property * -ExcludeProperty Connection,Table,Columns | Export-Csv -Path c:\myInboxData.csv -NoTypeInformation

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

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

 
PS C:\> $conn  = Connect-Gmail -User 'MyUser' -Password 'MyPassword'
PS C:\> $row = Select-Gmail -Connection $conn -Table "Inbox" -Columns (Id, MessageBody) -Where "From = '[email protected]'" | select -first 1
PS C:\> $row | ConvertTo-Json
{
  "Connection":  {

  },
  "Table":  "Inbox",
  "Columns":  [

  ],
  "Id":  "MyId",
  "MessageBody":  "MyMessageBody"
} 

データの削除

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

Select-Gmail -Connection $conn -Table Inbox -Where "From = '[email protected]'" | Remove-Gmail

データの変更

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

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