アクションとは、ユーザがアプリケーション上でとることができる社会的行動です。アクションを生成する前に、Dev AppObjectsActionsを定義してください


Creating Actions

アクションはDev Appを用いて定義します。アクションが定義されると、アプリケーションはAPIを用いてアクションのインスタンスを生成できるようになります。これによってユーザとオブジェクトのインスタンスの間の繋がりが成り立ちます。

POST /me/{namespace}:{action-type-name}
以下のAPI呼び出しでは、閲覧ユーザとPumpkin Pie(recipebox:cookのオブジェクトインスタンス)との間に「読んだ(read)」という繋がりを作ります。
https://graph.facebook.com/me/recipebox:cook?
  recipe=http://www.example.com/pumpkinpie.html&access_token=YOUR_ACCESS_TOKEN

注意 - App Access Tokenを用いて、認証されたユーザのアクションを投稿することも可能です。アクションが投稿されると、友人のニュースフィードやリアルタイムフィードに流れます。

ニュースフィード上

a


リアルタイムフィード上

a1


Previewing Stories from Published Actions

生成されるアクションは、https://www.facebook.com/USER_ID/activity/STORY_ID, where USER_IDでプレビューできます。USER_IDにはユーザのFacebook IDもしくはusernameが入り、STORY_IDにはいかに説明するaction-instance-idが入ります。

例えば以下のようなURLになります

https://www.facebook.com/dhirenp/activity/10100657260775943

プレビューを確認するには、ユーザはアプリケーションに対して適切なパーミッションを与えていなくてはなりません。

Required Parameters

Name Value Type
property_name URLもしくはグラフ上のオブジェクトID

該当URLのオブジェクトがグラフ上に存在しない場合、スクレイピングの対象となります。
string

Optional Parameters

Name Value Type
start_time アクション開始時刻ISO-8601 date-time
end_time アクション終了時刻ISO-8601 date-time
expires_in アクションが「古い」とみなされるまでの秒数。この秒数が経過するまではアクションは「現在形」で扱われ、それ以降は「過去形」となります。

expires_inは、アクション開始から終了までの期間を秒数で求めるほうが便利な場合に、end_time指定の代わりともなります。例えば、ユーザが映画を見始めたときのwatchアクションを投稿するとき、expires_inは映画の上映時間の秒数です。
integer
place アクションをとった場所を示すIDです。たとえばSimon ate Pizza at Facebook HQです。id
tags アクションに紐づけられた人物のIDです。たとえば、Carl, Vlad, and Paul visited Dolores Parkです。a string of comma separated ids
ref Facebook上に表示されるOpen Graphアクションをクリックしてサイトへ流入するとき、fb_refパラメータが渡されます。これはA/Bテストや、アクションに関連するデータをトラッキングする際に有用です。

デフォルトでは、refパラメータは7日間500個のユニークな値を受け付けます。insight上ではこれらの値毎にグルーピングされたグラフが表示されます。

7日間中で500個よりも多い値が必要な場合、たとえばrefパラメータにユニークIDを渡す場合などは、__セパレータを用いることができます。このセパレータの左側の文字列はInsightsでインデックスとして用いられ、A/Bテストの結果を解析する助けとなります。セパレータの右側にある文字列はInsightsでは無視され、7日間500個の勘定に入りませんが、ユーザがOpen Graphアクションのリンクから導入する際にはfb_refパラメータで渡されます。
string
scrape trueが指定された場合、アクションを生成する前にオブジェクトをスクレイピングしてプロパティを更新します。スクレイピングするのでレスポンスが遅くなりますから、オブジェクトが更新された場合に飲みスクレイピングさせてください。
bool

Response

{
  id: “{action-instance-id}”
}

Action typeで定義されていない追加プロパティが送られてきた場合、エラーが返されます。

Setting custom action instance properties

アクションのインスタンスが生成されるときには必ずカスタムアクションプロパティがセットされなくてはなりません。下記のような形式でパラメータを指定します。

{custom-property-name}={value}

以下の例が、カスタムプロパティ(recipebox:cookアクションのrating)のセット方法を示しています。

https://graph.facebook.com/me/recipebox:cook?
  book=http://www.example.com/pumpkinpie.html&rating=10

Tagging people and places

アクションはplace,tagsパラメータの指定によって、場所や人物をタグ付けすることができます。以下のパラメータで、Zhen read The Great Gatsby with Austin and Vlad at Ritual Coffee Roasters on Readlyというアクションが生成されます。

  • tags - Facebook User IDをカンマ区切りで。
  • place - アクションが起こった場所のPage ID。Graph APIを用いてPLACE IDを検索できます。
    • type=placeを指定する
    • クエリパラメータのqを指定
    • distanceは必須ではありません
https://graph.facebook.com/search?
  q=coffee&
  type=place&
  center=37.76,122.427&
  distance=1000
https://graph.facebook.com/me/recipebox:cook?
  book=http://www.example.com/pumpkinpie.html&
  place=145768288146&
  tags=208576,507763995&access_token=YOUR_ACCESS_TOKEN

Reading an Action

アプリケーションを認可したユーザのアクションを読み取ることも可能です。例えば、Recipeアプリケーションは私が料理/計画したレシピを読み取り、そのデータを元にアプリケーション体験をカスタマイズできます。

このAPIは、タイムスタンプやカスタムプロパティとその値などのメタデータを返します。アクションから参照されるオブジェクトは一階層の深さで返されます。

GET /{action-instance-id}

下記のように任意のアクションインスタンスを取得します

https://graph.facebook.com/1538292028372
      ?access_token=USER_ACCESS_TOKEN

Response

{
    "id": "1538292028372"
    "start_time": 1303502229, 
    "end_time": 1303513029, 
    "data": {
        "type": "recipebox:recipe", 
        "url": "http://www.example.com/pumpkinpie.html", 
        "id": "1234567890", 
        "title": "Pumpkin Pie"
    }, 
}

Note watch/news.read(Social Barにより投稿されるアクション)を指定することにより、ビルトインアクションを探すこともできます。


Updating an Action

下記のようにしてアクションインスタンスのプロパティを更新することも可能です。

POST /{action-instance-id}

下記のサンプルではアクションのend_timeを更新しています。

https://graph.facebook.com/1538292028372?expires_in=300
      &access_token=YOUR_ACCESS_TOKEN

Response

true

Deleting an Action

アプリケーションを認可したユーザのアクションを削除することも可能です。ユーザが遡ってアクティビティを削除しようとする場合に使ってください。ユーザコントロールのベストプラクティスに関してはOpen Graph Best Practices Guideをご覧ください。

DELETE /{action-instance-id}

以下のサンプルはアクションインスタンス1538292028372を削除します。

https://graph.facebook.com/1538292028372?&access_token=YOUR_ACCESS_TOKEN

Response

true 

Liking an Action

任意のアクションとユーザの間にLikeコネクションを生成します。
POST /{action-instance-id}/likes

以下のサンプルはユーザとアクションインスタンス1538292028372のあいだにLikeコネクションを生成しています。

https://graph.facebook.com/1538292028372/likes
      ?&access_token=YOUR_ACCESS_TOKEN

アクションインスタンスに紐づいたlikeを取得するには以下のようにします。

GET /{action-instance-id}/likes

Commenting on an Action

任意のアクションにユーザのコメントを追加するには以下のようにします。

POST /{action-instance-id}/comments

任意のアクションに対するユーザのコメントを取得するには以下のようにします。

GET /{action-instance-id}/comments

アクションのコメントを取得する詳細については、こちらで解説されています。



Timestamps

Action’s timestamps can be configured to describe actions that occur at different times and how actions appear on the user's profile and News Feed.

アクションのタイムスタンプは、アクションが異なる時刻に発生したり、ユーザのプロフィールやニュースフィードでどのように表示されるかを決定します。

Supported configurations for timestamps are:

タイムスタンプの設定でサポートされているのは以下の通りです。

  • API呼び出しが行われた時刻(デフォルト。例:投票など)
  • 過去に開始し、過去に終了する(例:去年の夏にプレーしたサッカーチーム)
  • 過去に開始し、未来に終了する(例:学期中に生徒が受講するクラス)
  • 現在開始し、未来に終了する(例:交際ステータス)
  • 現在開始し、終了は不定(例:「いいね!」や「欲しい」)
全てのケースにおいて、秒数で指定されるexpires_inの値は、start_timeから相対的にend_timeを指定する方法として利用できます。expires_inとend_time両方を同じアクションインスタンスに指定するのは受け入れられません。アプリケーションがexpires_inを指定した場合、end_timeは下記のように算出されます。
end_time = start_time + expires_in

旅行が長引いたとかクラスの受講を止めるなどでアクションのend_timeが変更する場合は、end_timeを更新できます。

Timestamps and collections

タイムスタンプを用いてアクションの状態を確かめることで、集合を形成することができます。例えば、start_dateが過去でend_dateが未来のenrolledアクションを取得することで、生徒が現在履修中のクラスの集合を取得できます。
同様にして、1998年の3月に私が履修していたクラスを、start_dateがMarch 1, 1998以前でend_dateがMarch 31, 1998以降のenrolledアクションを探すことで取得できます。

この方法を用いて、"like"や"want"などの恒久的なアクションの集合を求めることも可能です。