接続の確立
CData Cmdlets ユーザーは、データモジュールをインストールし、接続プロパティを設定してスクリプトを開始できます。このセクションでは、CSV インポートおよびエクスポートcmdlet などのネイティブPowerShell cmdlet でHubSpot Cmdlets を使用する例を示します。
インストールおよび接続
PSGet がある場合は、PowerShell Gallery から次のコマンドを使ってcmdlet をインストールできます。CData サイトからセットアップを取得することもできます。
Install-Module HubSpotCmdlets
プロファイルに以下を追加すると、次のセッションでcmdlet がロードされます。
Import-Module HubSpotCmdlets;
Connect-HubSpot cmdlet を使って、別のcmdlet に渡すことができる接続オブジェクトを作成します。
$conn = Connect-HubSpot
HubSpot への認証
HubSpot データソースへの接続に使用できる認証方法は2つあります。非公開アプリトークンベースおよびOAuth 認証です。
HubspotV3 スキーマのいくつかのテーブルは、OAuth の仕組みでは動作しないかもしれません。API 制限のため、これらのスキーマはPrivateAppToken ベース認証での使用に限定されます。具体的には、データモデルセクションの各テーブルで、サポートされる認証方法を説明します。
OAuth
AuthScheme は、すべてのOAuth フローでOAuth に設定する必要があります。以下のOAuth フローは、すでに設定済みであることを前提として書かれています。
デスクトップアプリケーション
CData は、OAuth デスクトップ認証を簡略化する埋め込みOAuth アプリケーションを提供します。代わりに、カスタムOAuth アプリケーションを作成することも可能です。カスタムアプリケーションの作成およびその理由については、カスタムOAuth アプリの作成 を参照してください。OAuth アクセストークンの取得およびリフレッシュ
以下を設定して、接続してください。
- OAuthClientId(カスタムアプリのみ):アプリケーションの登録時に割り当てられたクライアントId に設定。
- OAuthClientSecret(カスタムアプリのみ):アプリケーションの登録時に割り当てられたクライアントシークレットに設定。
- CallbackURL(カスタムアプリのみ):アプリケーションの登録時に定義されたリダイレクトURI に設定。
ヘッドレスマシン
ヘッドレスマシンのユーザーアカウントでOAuth を使用するようにドライバーを設定するには、インターネットブラウザに対応した別の端末で認証する必要があります。
- 以下のオプションから選択します。
- オプション1:後述の「Verifier code を取得および交換」に従い、OAuthVerifier 値を取得します。
- オプション2:インターネットブラウザに対応したマシンに本製品 をインストールし、後述の「OAuth 設定を転送」の説明に従い、通常のブラウザベースのフローで認証後にOAuth 認証値を転送します。
- 次に、ヘッドレスマシンからアクセストークンを自動的にリフレッシュするように本製品 を設定します。
オプション1:Verifier code を取得および交換
Verifier code を取得するには、OAuth Authorization URL で認証する必要があります。
インターネットブラウザに対応したマシンから認証してOAuthVerifier 接続プロパティを取得する方法は次のとおりです。
- 以下のオプションから選択します。
- 埋め込みOAuth アプリケーションを使用する場合は、GetOAuthAuthorizationURL ストアドプロシージャを呼び出します。ストアドプロシージャによって返されたURL をブラウザで開きます。
- カスタムOAuth アプリケーションを使用するには、以下のプロパティを設定します。
- InitiateOAuth:OFF に設定。
- OAuthClientId:アプリケーションの登録時に割り当てられたクライアントId に設定。
- OAuthClientSecret:アプリケーションの登録時に割り当てられたクライアントシークレットに設定。
- ログインして、本製品 にアクセス許可を与えます。すると、リダイレクトURI にリダイレクトされます。リダイレクトURI にはcode というパラメータが付加されます。このパラメータの値を控えておきます。後ほどこれをOAuthVerifier 接続プロパティに設定します。
ヘッドレスマシンでは、次の接続プロパティを設定してOAuth 認証値を取得します。
- InitiateOAuth:REFRESH に設定。
- OAuthVerifier:これを、控えておいたverifier code(リダイレクトURI のcode パラメータの値)に設定します。
- OAuthClientId:(カスタムアプリのみ)カスタムOAuth アプリケーション設定のクライアントId に設定。
- OAuthClientSecret:(カスタムアプリのみ)カスタムOAuth アプリケーション設定のクライアントシークレットに設定。
- OAuthSettingsLocation:これを設定すると、暗号化されたOAuth 認証値が指定された場所に永続化されます。
接続をテストしてOAuth 設定ファイルを生成し、以下のプロパティを再設定して接続します。
- InitiateOAuth:REFRESH に設定。
- OAuthClientId:(カスタムアプリのみ)アプリケーションの登録時に割り当てられたクライアントId に設定。
- OAuthClientSecret:(カスタムアプリのみ)アプリケーションの登録時に割り当てられたクライアントシークレットに設定。
- OAuthSettingsLocation:暗号化されたOAuth 認証値を含む場所に設定。アクセストークンの自動リフレッシュを有効にするために、この場所が本製品 に読み書きのアクセス許可を与えることを確認してください。
オプション2:OAuth 設定を転送
ヘッドレスマシンでの接続に先立ち、インターネットブラウザに対応したデバイスでドライバーとの接続をインストールし、作成する必要があります。上述の「デスクトップアプリケーション」の説明に従って、接続プロパティを設定します。
「デスクトップアプリケーション」の手順が完了すると、生成された認証値は、OAuthSettingsLocation で指定された場所に暗号化されて書き込まれます。デフォルトのファイル名はOAuthSettings.txt です。
接続をテストしてOAuth 設定ファイルを生成し、OAuth 設定ファイルをヘッドレスマシンにコピーします。
ヘッドレスマシンで、次の接続プロパティを設定し、データに接続します。
- InitiateOAuth:REFRESH に設定。
- OAuthClientId:(カスタムアプリのみ)アプリケーションの登録時に割り当てられたクライアントId に設定。
- OAuthClientSecret:(カスタムアプリのみ)アプリケーションの登録時に割り当てられたクライアントシークレットに設定。
- OAuthSettingsLocation:ブラウザでマシンからコピーしたOAuth 設定ファイルの場所に設定。アクセストークンの自動リフレッシュを有効にするために、この場所が本製品 に読み書きのアクセス許可を与えることを確認してください。
非公開アプリトークン
AuthScheme プロパティをPrivateAppToken に設定し、OAuthAccessToken をアプリケーションのアクセストークンの値に設定するだけで、Hubspot 非公開アプリのトークンを使用した接続が可能です。
HubSpot 非公開アプリのトークンを生成するには次のステップを実行してください。
- HubSpot アカウントで、メインナビゲーションバーにある設定アイコンをクリックします。
- 左のサイドバーメニューから、連携 -> 非公開アプリに移動します。
- 非公開アプリを作成をクリックします。
- 基本情報タブでアプリケーションの詳細(名前、ロゴ、説明)を設定します。
- スコープタブで、非公開アプリケーションがアクセスできるようにしたい各スコープについて読み取りまたは書き込みを選択します。これは、ドライバーが取得できるデータを決定するものです。選択するスコープの推奨は、OAuthRequiredScopes およびOAuthOptionalScopes プロパティを参照してください。
- アプリケーションの設定が完了したら、右上のアプリを作成をクリックします。
- アプリケーションのアクセストークンの情報を確認し、作成を続行、トークンを表示の順にクリックします。
- これで、取得したトークンをOAuthAccessToken プロパティに設定できます(OAuthAccessToken は非公開アプリアクセストークンとOAuth アクセストークンに使用されます)。
AuthScheme をPrivateAppToken に設定すると、この認証スキームを強制できます。
データの取得
Select-HubSpot cmdlet はデータを取得するためのネイティブなPowerShell インターフェースを提供します。
$results = Select-HubSpot -Connection $conn -Table "Contacts" -Columns @("City, Country") -Where "VID='123456789'"Invoke-HubSpot cmdlet はSQL インターフェースを提供します。このcmdlet を使うと、Query パラメータを介してSQL クエリを実行できます。
cmdlet 出力のパイプ処理
cmdlet は行オブジェクトをパイプラインに一度に一行ずつ返します。以下は、結果をCSV ファイルにエクスポートします。
Select-HubSpot -Connection $conn -Table Contacts -Where "VID = '123456789'" | Select -Property * -ExcludeProperty Connection,Table,Columns | Export-Csv -Path c:\myContactsData.csv -NoTypeInformation
Select-HubSpot からの結果をSelect-Object cmdlet にパイプして、Export-CSV cmdlet にパイプする前にいくつかのプロパティを実行していることがわかるでしょう。これをする理由は、CData Cmdlets は接続、テーブル、およびカラムの情報を結果セットの各行オブジェクトに追加しますが、必ずしもその情報がCSV ファイルに必要ではないからです。
ただし、これによってcmdlet の出力を別のcmdlet にパイプすることが容易になります。以下に、結果セットをJSON に変換する例を示します。
PS C:\> $conn = Connect-HubSpot PS C:\> $row = Select-HubSpot -Connection $conn -Table "Contacts" -Columns (City, Country) -Where "VID = '123456789'" | select -first 1 PS C:\> $row | ConvertTo-Json { "Connection": { }, "Table": "Contacts", "Columns": [ ], "City": "MyCity", "Country": "MyCountry" }
データの削除
以下は、抽出条件に合うあらゆるレコードを削除します。
Select-HubSpot -Connection $conn -Table Contacts -Where "VID = '123456789'" | Remove-HubSpot
データの変更
cmdlet はデータクレンジング同様、データの変換を容易にします。次の例は、レコードがすでに存在するかどうか、挿入する前に更新が必要かどうかをチェックしてから、CSV ファイルのデータをHubSpot にロードします。
Import-Csv -Path C:\MyContactsUpdates.csv | %{ $record = Select-HubSpot -Connection $conn -Table Contacts -Where ("Id = `'"+$_.Id+"`'") if($record){ Update-HubSpot -Connection $conn -Table Contacts -Columns @("City","Country") -Values @($_.City, $_.Country) -Where "Id = `'$_.Id`'" }else{ Add-HubSpot -Connection $conn -Table Contacts -Columns @("City","Country") -Values @($_.City, $_.Country) } }