アプリサーバーからの送信リクエストを構築する

FCM アプリサーバーのプロトコルを使用すると、メッセージ リクエストを作成し、それらを次のタイプのターゲットに送信できます。

  • トピックの名前
  • 条件
  • 端末登録トークン
  • 端末グループ名(レガシー プロトコルのみ)

事前定義フィールドで構成される通知ペイロード、独自のユーザー定義フィールドのデータ ペイロード、またはそれら両方のタイプのペイロードを含むメッセージを使用して、メッセージを送信することができます。詳細については、メッセージのタイプを参照してください。このページの例では、v1 HTTP プロトコルで通知メッセージを送信する方法を示しています。また、レガシー HTTP および XMPP プロトコルによりメッセージを送信するためのガイダンスもあります。

HTTP でメッセージを送信するには、HTTP POST リクエストを FCM v1 エンドポイントに送信し、send メソッドを指定します。エンドポイント URL には、アプリの Firebase プロジェクトのプロジェクト ID が含まれている必要があります。これは Firebase コンソールの [プロジェクトの全般設定] タブに表示されます。次に例を示します。

POST https://fcm.googleapis.com/v1/projects/myproject-b5ae1/messages:send HTTP/1.1

リクエスト ヘッダーには、次のものが含まれている必要があります。

  • Content-type: application/json
  • Authorization: Bearer <valid Oauth 2.0 token for the service account of the Firebase project>

OAuth 2.0 アクセス トークンの詳細については、送信リクエストを承認するをご覧ください。

リクエスト本文には、オプションの JSON Key-Value ペア、およびメッセージの内容が含まれています。メッセージ本文のオプションの概要については、FCM メッセージについてを、また、さらに詳細な情報については API リファレンスをご覧ください。

特定の端末へのメッセージの送信

リクエスト本文で、token オブジェクトの message キーを、対象となる特定のアプリ インスタンスの登録トークンに設定します。登録トークンの詳細については、プラットフォームのクライアント設定情報をご覧ください。

HTTP POST リクエスト

POST https://fcm.googleapis.com/v1/projects/myproject-b5ae1/messages:send HTTP/1.1

Content-Type: application/json
Authorization: Bearer ya29.ElqKBGN2Ri_Uz...HnS_uNreA

{
  "message":{
    "token" : "bk3RNwTe3H0:CI2k_HHwgIpoDKCIZvvDMExUdFQ3P1...",
    "notification" : {
      "body" : "This is an FCM notification message!",
      "title" : "FCM Message",
      }
   }
}

cURL

curl -X POST -H "Authorization: Bearer ya29.ElqKBGN2Ri_Uz...HnS_uNreA" -H "Content-Type: application/json" -d '{
"message":{
  "notification": {
    "title": "FCM Message",
    "body": "This is an FCM Message",
  },
  "token": "bk3RNwTe3H0:CI2k_HHwgIpoDKCIZvvDMExUdFQ3P1..."
  }
}' "https://fcm.googleapis.com/v1/projects/myproject-b5ae1/messages:send"

HTTP レスポンス

{
    "name": "projects/myproject-b5ae1/messages/0:1500415314455276%31bd1c9631bd1c96"
}

トピックにメッセージを送信

Firebase Cloud Messaging トピックへのメッセージを送信する方法は、個々の端末やユーザー グループ宛てのメッセージを送信する場合とよく似ています。アプリサーバーはメッセージ本文の topic キーに yourTopic などの値を設定します。デベロッパーは、次の正規表現に一致する任意のトピック名を選択できます。"[a-zA-Z0-9-_.~%]+"

複数のトピックの組み合わせに送信する場合、アプリサーバーは condition キーに、対象のトピックを指定するブール条件を設定します。たとえば、TopicA と、TopicBTopicC のいずれかに登録された端末にメッセージを送信する場合は、次のようになります。

'TopicA' in topics && ('TopicB' in topics || 'TopicC' in topics)

FCM はまず、かっこ内の条件を評価し、次に左から右に式を評価していきます。上記の式では、いずれか 1 つのトピックだけに登録したユーザーはメッセージを受信しません。同様に、TopicA に登録していないユーザーはメッセージを受信しません。メッセージを受信するのは、次の組み合わせの場合のみです。

  • TopicA と TopicB
  • TopicA と TopicC

条件式には最大 5 つのトピックを含めることができ、かっこを使用できます。使用できる演算子は &&||! です。! の使用方法に注意してください。

!('TopicA' in topics)

この式では、どのトピックにも登録されていないアプリ インスタンスを含め、TopicA に登録されていないアプリ インスタンスすべてがメッセージを受信します。

アプリサーバーのキーの詳細については、リファレンス情報をご覧ください。

トピック HTTP POST リクエスト

単一のトピックに送信します。

POST https://fcm.googleapis.com/v1/projects/myproject-b5ae1/messages:send HTTP/1.1

Content-Type: application/json
Authorization: Bearer ya29.ElqKBGN2Ri_Uz...HnS_uNreA
{
  "message":{
    "topic" : "foo-bar",
    "notification" : {
      "body" : "This is a Firebase Cloud Messaging Topic Message!",
      "title" : "FCM Message",
      }
   }
}

次の cURL で送信します。

curl -X POST -H "Authorization: Bearer ya29.ElqKBGN2Ri_Uz...HnS_uNreA" -H "Content-Type: application/json" -d '{
  "notification": {
    "title": "FCM Message",
    "body": "This is a Firebase Cloud Messaging Topic Message!",
  },
  "topic" : "foo-bar"
}' "https://fcm.googleapis.com/v1/projects/myproject-b5ae1/messages:send HTTP/1.1"

「犬」('dogs')または「猫」('cats')のトピックに登録された端末に送信します。

POST https://fcm.googleapis.com/v1/projects/myproject-b5ae1/messages:send HTTP/1.1

Content-Type: application/json
Authorization: Bearer ya29.ElqKBGN2Ri_Uz...HnS_uNreA
{
   "message":{
    "condition": "'dogs' in topics || 'cats' in topics",
    "notification" : {
      "body" : "This is a Firebase Cloud Messaging Topic Message!",
      "title" : "FCM Message",
    }
  }
}

次の cURL で送信します。

curl -X POST -H "Authorization: Bearer ya29.ElqKBGN2Ri_Uz...HnS_uNreA" -H "Content-Type: application/json" -d '{
  "notification": {
    "title": "FCM Message",
    "body": "This is a Firebase Cloud Messaging Topic Message!",
  },
  "condition": "'dogs' in topics || 'cats' in topics"
}' "https://fcm.googleapis.com/v1/projects/myproject-b5ae1/messages:send HTTP/1.1"

トピック HTTP レスポンス

{
    "name": "projects/myproject-b5ae1/messages/5735743068807585451"
}

メッセージ オプションの完全なリストについては、HTTP v1 API リファレンスをご覧ください。

レガシー アプリサーバーのプロトコルを使用してメッセージを送信する

レガシー プロトコルを使用する場合は、このセクションに示すようにメッセージ リクエストを作成します。HTTP で複数のプラットフォームに送信する場合は、v1 プロトコルによってメッセージ リクエストが簡素化されることがありますので注意してください。

特定の端末へのメッセージの送信

特定の端末にメッセージを送信するには、to キーを特定のアプリ インスタンスの登録トークンに設定します。登録トークンの詳細については、プラットフォームのクライアント設定情報をご覧ください。

HTTP POST リクエスト

https://fcm.googleapis.com/fcm/send
Content-Type:application/json
Authorization:key=AIzaSyZ-1u...0GBYzPu7Udno5aA

{ "data": {
    "score": "5x1",
    "time": "15:10"
  },
  "to" : "bk3RNwTe3H0:CI2k_HHwgIpoDKCIZvvDMExUdFQ3P1..."
}

HTTP レスポンス

{ "multicast_id": 108,
  "success": 1,
  "failure": 0,
  "results": [
    { "message_id": "1:08" }
  ]
}

XMPP メッセージ

<message id="">
  <gcm xmlns="google:mobile:data">
    { "data": {
      "score": "5x1",
      "time": "15:10"
    },
    "to" : "bk3RNwTe3H0:CI2k_HHwgIpoDKCIZvvDMExUdFQ3P1..."
  }
  </gcm>
</message>

XMPP レスポンス

<message id="">
  <gcm xmlns="google:mobile:data">
  {
      "from":"REGID",
      "message_id":"m-1366082849205"
      "message_type":"ack"
  }
  </gcm>
</message>

XMPP 接続サーバーには、他にもレスポンス用のオプションがあります。サーバー レスポンスの形式を参照してください。

ダウンストリーム メッセージをクライアント アプリに送信するときに使用可能なメッセージ オプションの完全な一覧については、選択した接続サーバー プロトコル(HTTP または XMPP)のリファレンス情報をご覧ください。

トピックにメッセージを送信

Firebase Cloud Messaging トピックへのメッセージを送信する方法は、個々の端末やユーザー グループ宛てのメッセージを送信する場合とよく似ています。アプリサーバーは to キーに /topics/yourTopic などの値を設定します。デベロッパーは、次の正規表現に一致する任意のトピック名を選択できます。"/topics/[a-zA-Z0-9-_.~%]+"

複数のトピックの組み合わせに送信する場合、アプリサーバーは(to キーではなく)condition キーで、対象のトピックを指定するブール条件を設定する必要があります。たとえば、TopicA と、TopicB または TopicC のいずれかに登録された端末にメッセージを送信する場合には、次のようになります。

'TopicA' in topics && ('TopicB' in topics || 'TopicC' in topics)

FCM はまず、かっこ内の条件を評価し、次に左から右に式を評価していきます。上記の式では、いずれか 1 つのトピックだけに登録したユーザーはメッセージを受信しません。同様に、TopicA に登録していないユーザーはメッセージを受信しません。メッセージを受信するのは、次の組み合わせの場合のみです。

  • TopicA と TopicB
  • TopicA と TopicC

条件式には最大 5 つのトピックを含めることができ、かっこを使用できます。使用できる演算子は &&||! です。! の使用方法に注意してください。

!('TopicA' in topics)

この式では、どのトピックにも登録されていないアプリ インスタンスを含め、TopicA に登録されていないアプリ インスタンスすべてがメッセージを受信します。

アプリサーバーのキーの詳細については、選択した接続サーバー プロトコル(HTTP または XMPP)のリファレンス情報をご覧ください。このページでは、メッセージをトピックに送信する方法として HTTP と XMPP の両方の例を示しています。

トピック HTTP POST リクエスト

単一のトピックに送信します。

https://fcm.googleapis.com/fcm/send
Content-Type:application/json
Authorization:key=AIzaSyZ-1u...0GBYzPu7Udno5aA
{
  "to": "/topics/foo-bar",
  "data": {
    "message": "This is a Firebase Cloud Messaging Topic Message!",
   }
}

「犬」('dogs')または「猫」('cats')のトピックに登録された端末に送信します。

https://fcm.googleapis.com/fcm/send
Content-Type:application/json
Authorization:key=AIzaSyZ-1u...0GBYzPu7Udno5aA
{
  "condition": "'dogs' in topics || 'cats' in topics",
  "data": {
    "message": "This is a Firebase Cloud Messaging Topic Message!",
   }
}

トピック HTTP レスポンス

//Success example:
{
  "message_id": "1023456"
}

//failure example:
{
  "error": "TopicsMessageRateExceeded"
}

トピック XMPP メッセージ

単一のトピックに送信します。

<message id="">
  <gcm xmlns="google:mobile:data">
{
  "to": "/topics/foo-bar",
  "data": {
    "message": "This is a Firebase Cloud Messaging Topic Message!",
   }
}

  </gcm>
</message>

「犬」('dogs')または「猫」('cats')のトピックに登録された端末に送信します。

<message id="">
  <gcm xmlns="google:mobile:data">
{
  "condition": "'dogs' in topics || 'cats' in topics",
  "data": {
    "message": "This is a Firebase Cloud Messaging Topic Message!",
   }
}

  </gcm>
</message>

トピック XMPP レスポンス

//Success example:
{
  "message_id": "1023456"
}

//failure example:
{
  "error": "TopicsMessageRateExceeded"
}

FCM サーバーがトピック送信リクエストに成功または失敗のレスポンスを返すまでに、最大 30 秒の遅延が発生する可能性があります。それに応じて、リクエスト内でアプリサーバーのタイムアウト値を必ず設定してください。

メッセージ オプションの完全な一覧については、選択した接続サーバー プロトコル(HTTP または XMPP)のリファレンス情報をご覧ください。

端末グループにメッセージを送信する

端末グループへメッセージを送信する方法は、個々の端末へメッセージを送信する場合とよく似ています。この場合、to パラメータを端末グループの一意の通知キーに設定します。ペイロード サポートの詳細については、メッセージのタイプをご覧ください。このページの例では、HTTP プロトコルと XMPP プロトコルで端末グループにデータ メッセージを送信する方法を示しています。

端末グループの HTTP POST リクエスト

https://fcm.googleapis.com/fcm/send
Content-Type:application/json
Authorization:key=AIzaSyZ-1u...0GBYzPu7Udno5aA

{
  "to": "aUniqueKey",
  "data": {
    "hello": "This is a Firebase Cloud Messaging Device Group Message!",
   }
}

端末グループの HTTP レスポンス

以下は「成功」の例です。notification_key には 2 つの登録トークンが関連付けられており、メッセージは両方のトークンに正しく送信されました。

{
  "success": 2,
  "failure": 0
}

以下は「一部成功」の例です。notification_key には 3 つの登録トークンが関連付けられています。メッセージは、そのうち 1 つの登録トークンだけに正しく送信されました。レスポンス メッセージには、メッセージを受信できなかった登録トークンがリストされます。

{
  "success":1,
  "failure":2,
  "failed_registration_ids":[
     "regId1",
     "regId2"
  ]
}

notification_key に関連付けられた 1 つ以上の登録トークンにメッセージを配信できない場合、アプリサーバーはバックオフを行いながら再試行を繰り返します。

メンバーのない端末グループにサーバーがメッセージを送信しようとすると、レスポンスには次のように成功 0 と失敗 0 が示されます。

{
  "success": 0,
  "failure": 0
}

端末グループの XMPP メッセージ

  <message id="">
  <gcm xmlns="google:mobile:data">
  {
      "to": "aUniqueKey",
      "message_id": "m-1366082849205" ,
      "data": {
          "hello":"This is a Firebase Cloud Messaging Device Group Message!"
      }
  }
  </gcm>
</message>

端末グループの XMPP レスポンス

グループ内のいずれか 1 つの端末にメッセージが正しく送信されると、XMPP 接続サーバーは ACK で応答します。グループ内のすべての端末に送信されたメッセージがすべて失敗した場合は、XMPP 接続サーバーは NACK で応答します。

以下は「成功」の例です。notification_key に 3 つの登録トークンが関連付けられており、メッセージはそれらすべてに正しく送信されました。

{
  "from": "aUniqueKey",
  "message_type": "ack",
  "success": 3,
  "failure": 0,
  "message_id": "m-1366082849205"
}

以下は「一部成功」の例です。notification_key には 3 つの登録トークンが関連付けられています。メッセージは、そのうち 1 つの登録トークンだけに正しく送信されました。レスポンス メッセージには、メッセージを受信できなかった登録トークンがリストされます。

{
  "from": "aUniqueKey",
  "message_type": "ack",
  "success":1,
  "failure":2,
  "failed_registration_ids":[
     "regId1",
     "regId2"
  ]
}

FCM 接続サーバーがグループ内のすべての端末への配信に失敗すると、アプリサーバーは NACK レスポンスを受け取ります。

メッセージ オプションの完全な一覧については、選択した接続サーバー プロトコル(HTTP または XMPP)のリファレンス情報をご覧ください。

フィードバックを送信...

ご不明な点がありましたら、Google のサポートページをご覧ください。