Cmdlets for Facebook

Build 24.0.9063

接続の確立

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

インストールおよび接続

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

Install-Module FacebookCmdlets

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

Import-Module FacebookCmdlets;

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

$conn = Connect-FB

Facebook への接続

Facebook に接続する前に、適切な接続プロパティを取得する必要があります。Facebook はOAuth によるユーザー認証のみをサポートしているため、CData が提供する組み込みOAuth アプリケーションを使用するか、カスタムOAuth アプリケーションの作成 で説明するようにカスタムOAuth アプリケーションを作成する必要があります。

さらに、以下のオプションの接続プロパティを設定することもできます。

  • Target：このプロパティは、クエリ結果を指定されたターゲットに合致するレコードに限定することを可能にします。 例えば、動画のコメントを取得するには、ターゲットとして動画のID を指定します。クエリ毎にこの制限をかけるには、テーブルのTarget カラムを使用します。
  • AggregateFormat：このプロパティは、集計カラムをJSON（デフォルトのフォーマット）ではなく、XML データとして返すことを可能にします。

Facebook への認証

以下のセクションでは、利用可能な任意のOAuth アクセスフローでのFacebook への認証について詳しく説明します。カスタムOAuth アプリケーションの作成については、カスタムOAuth アプリケーションの作成 を参照してください。

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

CData は、OAuth デスクトップ認証を簡略化する埋め込みOAuth アプリケーションを提供します。または、カスタムOAuth アプリケーションの作成 で説明するように、カスタムOAuth アプリケーションを作成することも可能です。

認証に関する2つの方法の違いは、カスタムOAuth アプリケーションを介して接続するために、以下の接続プロパティを設定する必要があることだけです。

  • OAuthClientId：（カスタムアプリケーションのみ）アプリケーション設定のクライアントId に設定。
  • OAuthClientSecret：（カスタムアプリケーションのみ）アプリケーション設定のクライアントシークレットに設定。
  • CallbackURL：アプリケーション設定のリダイレクトURL に設定。
  • Scope（オプション）：ドライバーがリクエストするアクセス権をカスタマイズする必要がある場合のみ設定します。
  • AuthenticateAsPage（オプション）：リクエストをページとして作成するには、これをページID に設定します。ページは認証されたユーザーにより管理されている必要があります。

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

Web アプリケーション

Web アプリケーション経由で接続する場合は、カスタムOAuth アプリケーションの作成 で説明するようにFacebook にカスタムOAuth アプリケーションを作成および登録する必要があります。 それから本製品 を使用してOAuth トークンの値を取得および管理します。

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

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

  • OAuthClientId：アプリケーション設定のクライアントId に設定。
  • OAuthClientSecret：アプリケーション設定のクライアントシークレットに設定。
  • Scope（オプション）：ドライバーがリクエストするアクセス権をカスタマイズする必要がある場合のみ設定。
  • AuthenticateAsPage（オプション）：リクエストをページとして作成するには、ページId に設定。ページは認証されたユーザーにより管理されている必要があります。

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

  1. GetOAuthAuthorizationURL ストアドプロシージャを呼び出します。AuthMode インプットをWEB に、CallbackURL インプットをアプリケーション設定で指定したリダイレクトURI に設定します。必要に応じて、"Scope" パラメータを設定してカスタム権限をリクエストします。
  2. URL を開き、ログインして、アプリケーションを認可します。コールバックURL にリダイレクトされます。
  3. GetOAuthAccessToken ストアドプロシージャを呼び出します。AuthMode インプットをWEB に設定します。Verifier インプットを、コールバックURL のクエリ文字列の"code" パラメータに設定します。必要に応じて、"Scope" パラメータを設定してカスタム権限をリクエストします。

OAuthAccessToken 接続プロパティをストアドプロシージャで返されたアクセストークンに設定し、データに接続します。ExpiresIn 秒後に、アクセストークンの期限が切れたときは、GetOAuthAccessToken を呼び出し、新しいアクセストークンを取得します。

ヘッドレスマシン

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

ヘッドレスOAuth フローでは、カスタムOAuth アプリの作成は任意です。アプリの作成をスキップしたい場合は、ドライバーの埋め込みOAuth クレデンシャルで接続できます。 しかしながら、カスタムOAuth アプリを作成すると、ユーザーがFacebook にログインしてドライバーにアクセス権を与えるときに表示される情報を変更することもできます。カスタムOAuth アプリケーションの作成については、カスタムOAuth アプリケーションの作成 を参照してください。

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

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

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

  1. 埋め込みOAuth アプリケーションを使用する場合：
    1. GetOAuthAuthorizationURL ストアドプロシージャを呼び出します。
    2. Facebook OAuth endpoint をクリックし、ブラウザでエンドポイントを開きます。
  2. カスタムOAuth アプリケーションを使用するには、以下のプロパティを設定し、認証URL を作成します。
    • InitiateOAuth：OFF に設定。
    • OAuthClientId：アプリケーションの登録時に割り当てられたクライアントId に設定。
    • OAuthClientSecret：アプリケーションの登録時に割り当てられたクライアントシークレットに設定。
  3. CallbackURI 入力パラメータを、アプリケーション設定で指定した正確なリダイレクトURI に設定してGetOAuthAuthorizationURL ストアドプロシージャを呼び出します。
  4. ストアドプロシージャによって返されたURL をブラウザで開きます。
  5. ログインして、本製品 にアクセス許可を与えます。すると、verifier code を含むコールバックURL にリダイレクトされます。
  6. verifier code の値を保存します。後ほどこれをOAuthVerifier 接続プロパティに設定します。

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

  • OAuthClientId：OAuth 統合設定のクライアントID に設定。
  • OAuthClientSecret：OAuth 統合設定のクライアントシークレットに設定。
  • OAuthVerifier：verifier code に設定。
  • OAuthSettingsLocation：暗号化されたOAuth 認証値を指定された場所に永続化。
  • InitiateOAuth：REFRESH に設定。

データへの接続

OAuth 設定ファイルが生成されたら、次のプロパティを設定してデータに接続します。

  • OAuthSettingsLocation：暗号化されたOAuth 認証値が保存される場所に設定。アクセストークンの自動リフレッシュを有効にするために、この場所がプロバイダーに読み書きのアクセス許可を与えることを確認してください。
  • InitiateOAuth：REFRESH に設定。

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

別のマシンに本製品 をインストールするには、認証してから、結果のOAuth 値を転送します。

  1. セカンドマシンに、本製品 をインストールして、次の接続プロパティセットで接続します。
    • OAuthSettingsLocation：書き込み可能な場所に設定。
    • OAuthClientId：アプリケーション設定のクライアントID に設定。
    • OAuthClientSecret：アプリケーション設定のクライアントシークレットに設定。
    • CallbackURL：アプリケーション設定のコールバックURL に設定。
  2. 認証する接続をテストします。生成された認証値は、OAuthSettingsLocation で指定されたパスに書き込まれて暗号化されます。接続テストに成功したら、OAuth 設定ファイルをヘッドレスマシンにコピーします。ヘッドレスマシンで、次の接続プロパティを設定し、データに接続します。
    • InitiateOAuth：REFRESH に設定。
    • OAuthSettingsLocation：OAuth 設定ファイルの場所に設定。アクセストークンの自動リフレッシュを有効にするために、この場所が本製品 に読み書きのアクセス許可を与えることを確認してください。

追加認証のリクエスト

本製品 の使用中に、指定のアクションを行う権限がアプリにありませんというエラーメッセージがFacebook から返されることがあります。 このエラーを解消するには、必要な権限を持つ新しいOAuth アクセストークンを発行する必要があります。認証ステップでデスクトップアプリケーション用のScope プロパティを設定します。 利用可能なFacebook アクセス許可のリストはこちらで確認できます。

http://developers.facebook.com/docs/authentication/permissions/

ユースケースに応じて必要な許可は次のとおりです。

user_birthday, user_photos, user_videos, user_likes, user_hometown, user_location, read_insights, pages_manage_metadata, pages_read_engagement, pages_read_user_content, pages_messaging, business_management, instagram_basic, instagram_manage_insights

場合によっては、アクセス許可の制限は、リクエスト可能なFacebook OAuth パーミッションが見つからないことが原因ではなく、Page Public Content Access やPage Public Metadata Access のようなOAuth アプリ機能が見つからないことが原因かもしれないことに注意してください。これらの機能はOAuth アプリ全体に紐づいており、ユーザーが要求した個々のOAuth アクセストークンに対して承認や拒否を行うことはできません。埋め込みOAuth アプリでは利用できないアプリ機能へのアクセスが必要な場合は、カスタムOAuth アプリケーションの作成 を検討してください。

AuthenticateAsPage プロパティ

単一ページとして投稿する場合は、AuthenticateAsPage 接続プロパティを使用します。ページのコレクションをクエリする場合は、AuthenticateAsPage を空のままにします。その場合、CData ツールはどのページトークンを使用するかを自動的に検出します。

次のセクションでは、2つのオプションについて比較します。

ページとして投稿

Facebook に認証した後、あなたのユーザーアカウントで管理するページとして投稿をすることができます。AuthenticateAsPage プロパティを使用するページのID に設定します。Pages ビューをクエリして、あなたのアカウントでアクセスすることが可能なすべてのページのID を見ることができます。

自動ページ

Facebook では、ページが所有するほとんどのリソースに対してページトークンを必要とする多くの変更を最近加えました。これは、複数のページを管理していてすべてのページで同じクエリを実行したい場合（例えばInsights を取得する場合など）に面倒です。CData のツールでこれをシームレスに処理するために、使用するページトークンを自動的に検出する方法を追加しました。これを機能させるには、AuthenticateAsPage を指定しないでください。正しいページトークンは、リクエストでターゲットの一部としてページID が指定されている場合にのみ解決できます。つまり、リクエストによっては手動でAuthenticateAsPage を指定する必要があります。

データの取得

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

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

cmdlet 出力のパイプ処理

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

Select-FB -Connection $conn -Table Posts -Where "Target = '11111'" | Select -Property * -ExcludeProperty Connection,Table,Columns | Export-Csv -Path c:\myPostsData.csv -NoTypeInformation

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

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

 
PS C:\> $conn  = Connect-FB
PS C:\> $row = Select-FB -Connection $conn -Table "Posts" -Columns (ID, FromName) -Where "Target = '11111'" | select -first 1
PS C:\> $row | ConvertTo-Json
{
  "Connection":  {

  },
  "Table":  "Posts",
  "Columns":  [

  ],
  "ID":  "MyID",
  "FromName":  "MyFromName"
}

データの削除

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

Select-FB -Connection $conn -Table Posts -Where "Target = '11111'" | Remove-FB

データの変更

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

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

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