The first thing you need to do is to install PowerShell 2.0 and .NET Framework 3.5 (4.0 also works). If you’re running Windows 7 or Windows Server 2008 R2 or better, you get these by default. Otherwise, see http://microsoft.com/downloads
. You do not need to enable PSRemoting in order to use FacebookPSModule.
If you will be doing any serious script authoring, you will probably want to enable the PowerShell ISE feature. On Windows Server 2008 R2, you can do this from Control Panel -> Programs -> Turn Windows features on or off, or just by running “dism.exe /online /enable-feature /FeatureName:MicrosoftWindowsPowerShellISE”. Otherwise, see http://microsoft.com/downloads
The FacebookPSModule Downloads tab has full details on how to install FacebookPSModule.
Granting Facebook permissions to FacebookPSModule
Short answer: Skip this section and just start issuing commands, and FacebookPSModule will talk you through it.
Complete answer: The first thing you need to do is to grant FacebookPSModule permission to access your Facebook information, or the Facebook information of the account you intend to administer. From the standpoint of Facebook, FacebookPSModule is a “Facebook application”, even though it is not a web application. You can explicitly run “New-FBConnection”, or you can let FacebookPSModule do it for you automatically on your first command. This will cause a popup dialog containing the Facebook screen where you grant permissions to an application. Once you create an “access token”, it will by default be cached in %LOCALAPPDATA%\FacebookPowerShellModule_CachedToken.txt, so you will not have to re-enter it as long as you use your current user account.
However, there is a catch. The popup dialog can only be displayed if you are running PowerShell in “STA” mode (I’ll spare you the gory details on why this is the case). PowerShell ISE always runs in STA mode, but the plain command-line Powershell.exe does not. You can explicitly run “Powershell.exe –STA” to force it into STA mode. Once you have the cached access token, this is no longer necessary.
If you intend to manage a page rather than a user, you will need to first get access to the user, then get the PageID with Get-FBPage, and finally use New-FBConnection -PageId <pageid> to get access to the page. Once the page's "access token" is cached, you will manage the page instead of the user by default.
It is important to understand that the Facebook access token is a simple string which grants anyone who knows it broad permissions to do what they like with your Facebook account. You should be very careful with the access token, the CachedToken.txt file which contains it, and any PowerShell session which has loaded it. (Technically, the file contains an encrypted version of the access token, but anyone with access to your user account can decrypt it.) You should expect that the cached access token will need to be refreshed if you update your Facebook password.
At this writing (version 0.6.0 1/22/2012), FacebookPS exports 24 commands. Most of these commands work through the Facebook Graph API, discussed in detail at http://developers.facebook.com/docs/reference/api/
. You should not need to understand this API in detail in order to use FacebookPSModule, but you will want to use that link as a reference to see what fields are available.
All Facebook objects have an ID, which is a simple string (usually a number). You will need to specify this ID in order to load information about a specific object. The account owning the current access token can always be accessed as “me”. You can use PowerShell pipelines to pass the ID from one command to another, for example “Get-FBFriends | Show-FBMessageDialog”. Most object will have an "Id" field and also another field named specifically for the object type, for example "UserId" or "GroupId".
The most important functions are:New-FBConnection
: This command sets up the initial Facebook connection which you will need to use most other commands. You will only need to do this once, after that the connection will be cached in your Windows profile.Get-FBFriend
: This command retrieves the list of friends of the specified user. Note that default Facebook permissions do not permit Facebook applications to retrieve “friends of friends” lists, even though these are available from the Facebook GUI. This is a limitation of the Facebook API, not of FacebookPSModule.Get-FBAlbum
: These commands similarly retrieve other classes of information.Get-FBEvent
: This command retrieves the list of events of the specified user or group. Only “future” events will be retrieved, and only if the user has not explicitly responded “will not attend”.Get-FBMember
: Retrieves the list of members of a group.Get-FBAssociation
: This is a worker function for Get-FBFriends, Events and Feed, but it also provides access to other “Connections” offered by the Facebook Graph API for which specific commands are not yet available.Get-FBObjectData
: This retrieves data on a specific object. The object can be of any type. The –Fields parameter specifies the data to retrieve; if you do not specify this, Facebook will choose a default set of fields depending on the object type. Get-FBObjectData returns a single object with parameters corresponding to the requested fields. Individual fields may not be present on the return object if they are not specified for the Facebook object, or if you do not have permission to retrieve them. Note that most Get-FB* commands have a -Fields parameter; it is generally more efficient to retrieve them up front rather than make multiple calls to Get-FBObjectData.Add-FBBulkPhotos
: Copy multiple photos to a Facebook album
*Read-FBBulkPhotos: Copy all the photos in a Facebook album to files, or all the photos in all Facebook albums.New-FBPost
: Creates a new post in the user or page feed.New-FBEvent
: This command creates a new Facebook event for the current user.New-FBEventInvite
: Invites users to an existing event.New-FBPhoto
: Upload a photo from your computer to a Facebook album.Show-FBMessageDialog
: This command helps send bulk Facebook messages. Facebook does not permit sending messages to be completely automated, but you can use this command to send messages with just a few clicks for each group of 50 recipients.
Examples of more complex operations
FacebookPSModule, plus the built-in commands in PowerShell, enable you to perform complex operations with only one or a few lines of script. I have provided a few examples in FacebookExamples.ps1, available as part of the download. These include:Backup-FBFriends
: This reads your current friends list and backs it up to c:\temp$timestring.csv. You can analyze this file in Excel, or use import-csv and compare-object to monitor changes to your friends list over time (de-friendings etc).Get-FBEventsFromFeed
: This reads all the events from the feed for a specific owner. I use this for finding events belonging to a specific group.Write-FBRSVPs
: Read all the RSVPs for the specified event, and write them to different CSV files. Put this in a repeating Scheduled Task, and you’ll always have RSVP lists at your fingertips! This was an important scenario for my lead customer.
Thank you for reading this far, and I hope FacebookPSModule helps you with your work! I would really appreciate it if anyone trying this out would put some brief notes in the Discussion tab. At this writing (12/03/2011), FacebookPSModule is still in Alpha, and I have lots of exciting ideas on how to improve it.