مرجع سرور

اجرای سرور اختیاری است. اگر می خواهید این عملیات را انجام دهید از سرویس Instance ID استفاده کنید:

اطلاعاتی در مورد نمونه های برنامه دریافت کنید

برای دریافت اطلاعات در مورد یک نمونه برنامه، با سرویس Instance ID در این نقطه پایانی تماس بگیرید و رمز نمونه برنامه را مطابق شکل ارائه کنید:

 https://iid.googleapis.com/iid/info/IID_TOKEN

مولفه های

  • Authorization : key=YOUR_API_KEY. این پارامتر را در هدر تنظیم کنید.
  • details بولی [اختیاری]: این پارامتر پرس و جو را روی true تنظیم کنید تا اطلاعات اشتراک موضوع FCM یا GCM (در صورت وجود) مرتبط با این نشانه را دریافت کنید. وقتی مشخص نیست، پیش‌فرض روی false است.

نتایج

در صورت موفقیت، تماس وضعیت HTTP 200 و یک شی JSON حاوی:

  • application - نام بسته مرتبط با توکن.
  • authorizedEntity - projectId مجاز به ارسال به توکن.
  • applicationVersion - نسخه برنامه.
  • appSigner - اثر انگشت sha1 برای امضای اعمال شده روی بسته. نشان می دهد که کدام طرف برنامه را امضا کرده است. به عنوان مثال، Play Store .
  • platform - ANDROID ، IOS ، یا CHROME را برای نشان دادن پلتفرم دستگاهی که توکن به آن تعلق دارد، برمی‌گرداند.

اگر پرچم details تنظیم شده باشد:

  • rel - روابط مرتبط با توکن. به عنوان مثال، لیستی از اشتراک موضوع.

مثال درخواست GET

https://iid.googleapis.com/iid/info/nKctODamlM4:CKrh_PC8kIb7O...clJONHoA?Authorization:key=AIzaSyZ-1u...0GBYzPu7Udno5aA

نتیجه مثال

HTTP 200 OK
{
  "application":"com.iid.example",
  "authorizedEntity":"123456782354",
  "platform":"Android",
  "appSigner":"1a2bc3d4e5"
  "rel":{
    "topics":{
      "topicname1":{"addDate":"2015-07-30"},
      "topicname2":{"addDate":"2015-07-30"},
      "topicname3":{"addDate":"2015-07-30"},
      "topicname4":{"addDate":"2015-07-30"}
    }
  }
}

ایجاد نقشه های رابطه برای نمونه های برنامه

Instance ID API به شما امکان می دهد نقشه های ارتباطی را برای نمونه های برنامه ایجاد کنید. به عنوان مثال، می‌توانید یک نشانه ثبت نام را به موضوع پیام‌رسانی Google Cloud نگاشت و نمونه برنامه را در آن موضوع مشترک کنید. API روش هایی را برای ایجاد چنین روابطی هم به صورت جداگانه و هم به صورت انبوه ارائه می دهد.

یک نگاشت رابطه برای یک نمونه برنامه ایجاد کنید

با توجه به یک نشانه ثبت نام و یک رابطه پشتیبانی شده، می توانید یک نقشه ایجاد کنید. برای مثال، می‌توانید با تماس با سرویس Instance ID در این نقطه پایانی، یک نمونه برنامه را در یک موضوع Google Cloud Messaging مشترک کنید، و توکن نمونه برنامه را مطابق شکل ارائه کنید:

 https://iid.googleapis.com/iid/v1/IID_TOKEN/rel/topics/TOPIC_NAME

مولفه های

  • Authorization : key=YOUR_API_KEY. این پارامتر را در هدر تنظیم کنید.

نتایج

در صورت موفقیت، تماس وضعیت HTTP 200 را برمی گرداند.

نمونه درخواست POST

https://iid.googleapis.com/iid/v1/nKctODamlM4:CKrh_PC8kIb7O...clJONHoA/rel/topics/movies
Content-Type:application/json
Content-Length: 0
Authorization:key=AIzaSyZ-1u...0GBYzPu7Udno5aA

نتیجه مثال

HTTP 200 OK
{}

نقشه های رابطه را برای چندین نمونه برنامه مدیریت کنید

با استفاده از روش های دسته ای سرویس Instance ID، می توانید مدیریت دسته ای نمونه های برنامه را انجام دهید. برای مثال، می‌توانید اضافه یا حذف انبوه نمونه‌های برنامه را به موضوع FCM یا GCM انجام دهید. برای به‌روزرسانی تا 1000 نمونه برنامه در هر تماس API، با سرویس Instance ID در این نقطه پایانی تماس بگیرید و توکن‌های نمونه برنامه را در بدنه JSON ارائه دهید:

 https://iid.googleapis.com/iid/v1:batchAdd

 https://iid.googleapis.com/iid/v1:batchRemove

مولفه های

  • Authorization : key=YOUR_API_KEY. این پارامتر را در هدر تنظیم کنید.
  • to : نام موضوع.
  • registration_tokens : آرایه ای از نشانه های IID برای نمونه های برنامه ای که می خواهید اضافه یا حذف کنید.

نتایج

در صورت موفقیت، تماس وضعیت HTTP 200 را برمی گرداند. نتایج خالی نشان دهنده اشتراک موفقیت آمیز برای توکن است. برای اشتراک های ناموفق، نتیجه حاوی یکی از این کدهای خطا است:

  • NOT_FOUND - رمز ثبت نام حذف شده یا برنامه حذف نصب شده است.
  • INVALID_ARGUMENT - رمز ثبت نام ارائه شده برای شناسه فرستنده معتبر نیست.
  • داخلی - سرور باطن به دلایل نامعلومی از کار افتاد. درخواست را دوباره امتحان کنید.
  • TOO_MANY_TOPICS - تعداد بیش از حد موضوعات در هر نمونه برنامه.
  • RESOURCE_EXHAUSTED - تعداد زیادی درخواست اشتراک یا لغو اشتراک در مدت زمان کوتاهی. با عقب نشینی نمایی دوباره امتحان کنید.

نمونه درخواست POST

https://iid.googleapis.com/iid/v1:batchAdd
Content-Type:application/json
Authorization:key=API_KEY
{
   "to": "/topics/movies",
   "registration_tokens": ["nKctODamlM4:CKrh_PC8kIb7O...", "1uoasi24:9jsjwuw...", "798aywu:cba420..."],
}

نتیجه مثال

HTTP 200 OK
{
  "results":[
    {},
    {"error":"NOT_FOUND"},
    {},
  ]
}

توکن های ثبت نام برای توکن های APN ایجاد کنید

با استفاده از روش batchImport سرویس Instance ID، می‌توانید توکن‌های APN موجود iOS را به صورت انبوه به پیام‌رسانی Google Cloud یا Firebase Cloud Messaging وارد کنید و آنها را به نشانه‌های ثبت معتبر نگاشت کنید. با ارائه لیستی از نشانه های APN در بدنه JSON، با سرویس Instance ID در این نقطه پایانی تماس بگیرید:

 https://iid.googleapis.com/iid/v1:batchImport

بدنه پاسخ حاوی آرایه‌ای از نشانه‌های ثبت شناسه نمونه است که آماده استفاده برای ارسال پیام‌های FCM یا GCM به توکن دستگاه APN مربوطه است.

مولفه های

  • Authorization : key=YOUR_API_KEY. این پارامتر را در هدر تنظیم کنید.
  • application : شناسه بسته نرم افزاری.
  • sandbox : Boolean برای نشان دادن محیط sandbox (TRUE) یا تولید (FALSE)
  • apns_tokens : آرایه ای از توکن های APN برای نمونه های برنامه ای که می خواهید اضافه یا حذف کنید. حداکثر 100 توکن در هر درخواست.

نتایج

در صورت موفقیت، تماس وضعیت HTTP 200 و بدنه نتیجه JSON را برمی‌گرداند. برای هر توکن APN ارائه شده در درخواست، لیست نتایج شامل موارد زیر است:

  • توکن APNs.
  • وضعیت. یا OK، یا یک پیام خطایی که خرابی را توصیف می کند.
  • برای نتایج موفقیت آمیز، نشانه ثبت نام که FCM یا GCM به توکن APN ها نگاشت می شود.

نمونه درخواست POST

https://iid.googleapis.com/iid/v1:batchImport
{
  "application": "com.google.FCMTestApp",
  "sandbox":false,
  "apns_tokens":[
      "368dde283db539abc4a6419b1795b6131194703b816e4f624ffa12",
      "76b39c2b2ceaadee8400b8868c2f45325ab9831c1998ed70859d86"
   ]
  }
}

نتیجه مثال

HTTP 200 OK
{
 "results":[
       {
        "apns_token": "368dde283db539abc4a6419b1795b6131194703b816e4f624ffa12",
         "status": "OK",
         "registration_token":"nKctODamlM4:CKrh_PC8kIb7O...clJONHoA"
       },
       {
         "apns_token": "76b39c2b2ceaadee8400b8868c2f45325ab9831c1998ed70859d86",
         "status":"Internal Server Error"
        },
     ]
  }

توکن های ثبت نام را برای اشتراک های فشار مدیریت کنید

با استفاده از روش های وب سرویس Instance ID، می توانید اشتراک های فشار موجود را برای Firebase Cloud Messaging وارد کنید. همچنین می توانید آنها را به روز رسانی و حذف کنید.

هنگامی که یک اشتراک پوش را وارد می کنید، یک نشانه ثبت نام دریافت می کنید. این توکن به شما امکان می‌دهد از ویژگی‌های FCM مانند پیام‌رسانی موضوعی و پیام‌رسانی گروهی دستگاه برای هدف‌یابی اعلان‌ها به برنامه‌های وب خود استفاده کنید.

وارد کردن اشتراک های فشار

می‌توانید اشتراک‌های push را با استفاده از نقطه پایانی وب InstanceID وارد کنید:

 https://iid.googleapis.com/v1/web/iid

درخواست باید شامل یک سرصفحه مجوز تنظیم شده روی یک نشانه دسترسی OAuth 2.0 ، یک سرصفحه کلید رمزنگاری تنظیم شده به کلید سرور برنامه شما و شی PushSubscription در بدنه درخواست باشد.

بدنه پاسخ حاوی یک رمز ثبت است که آماده استفاده برای ارسال پیام‌های FCM یا GCM به نمونه برنامه وب مربوطه بدون نیاز به رمزگذاری بار است.

جفت کلید VAPID خود را در کنسول آپلود کنید

برای وارد کردن کلیدها، باید به پروژه Firebase در سطح مالک دسترسی داشته باشید. کلید عمومی و خصوصی موجود خود را در قالب کدگذاری شده امن URL base64 وارد کنید:

  1. برگه Cloud Messaging را در قسمت تنظیمات کنسول Firebase باز کنید و به بخش پیکربندی وب بروید.
  2. در برگه Web Push Certificates ، متن پیوند «وارد کردن یک جفت کلید موجود» را پیدا کرده و انتخاب کنید.
  3. در گفتگوی وارد کردن جفت کلید ، کلیدهای عمومی و خصوصی خود را در فیلدهای مربوطه وارد کنید و روی واردات کلیک کنید. کنسول رشته کلید عمومی و تاریخ اضافه شدن را نمایش می دهد.

بازیابی نشانه OAuth2: از اعتبارنامه ها برای برش توکن های دسترسی استفاده کنید

برای ایجاد یک نشانه دسترسی برای درخواست، باید رمز دسترسی را برش داده و به درخواست HTTP اضافه کنید.

node.js

 function getAccessToken() {
  return admin.credential.applicationDefault().getAccessToken()
      .then(accessToken => {
        return accessToken.access_token;
      })
      .catch(err => {
        console.error('Unable to get access token');
        console.error(err);
      });
}

پایتون

def _get_access_token():
  """Retrieve a valid access token that can be used to authorize requests.

  :return: Access token.
  """
  credentials = ServiceAccountCredentials.from_json_keyfile_name(
      'service-account.json', SCOPES)
  access_token_info = credentials.get_access_token()
  return access_token_info.access_token

جاوا

private static String getAccessToken() throws IOException {
  GoogleCredentials googleCredentials = GoogleCredentials
          .fromStream(new FileInputStream("service-account.json"))
          .createScoped(Arrays.asList(SCOPES));
  googleCredentials.refreshAccessToken();
  return googleCredentials.getAccessToken().getTokenValue();
}

برای اجازه دسترسی به FCM، دامنه https://www.googleapis.com/auth/firebase.messaging را درخواست کنید.

مولفه های

  • مجوز: Bearer <access_token> . این پارامتر را در هدر تنظیم کنید.
  • Crypto-Key: p256ecdsa=APPLICATION_PUBLIC_KEY . این پارامتر را در هدر تنظیم کنید.
  • بدنه درخواست: PushSubscription.toJson() . اشتراک فشار را بدون تجزیه به بدنه HTTP منتقل کنید. محتوا با رمزگذاری W3C PushSubscription مطابقت دارد.

واکنش

در صورت موفقیت، تماس وضعیت HTTP 200 OK و بدنه نتیجه JSON حاوی رمز IID را برمی گرداند.

نمونه درخواست POST

 https://iid.googleapis.com/v1/web/iid
 Content-Type:application/json
 Authorization:Bearer ya29.ElqKBGN2Ri_Uz...HnS_uNreA
 Crypto-Key:p256ecdsa=BFv5XHxdkZgpQzCb-...8uI42kf4A4USEIMo
 {
   "endpoint": "https://fcm.googleapis.com/fcm/send/dS4xerbSlqU:APb...aRs4QP",
   "keys": {
         "auth": "7cdY...xxjwz46Q",
         "p256dh": "BH7xPjScJe...z9lbIZDmOV_c"
    }
 }

نتیجه مثال

HTTP 200 OK
{
 "token":"KctODamlM4:CKrh_PC...cl"
}

اشتراک های فشار را به روز کنید

با استفاده از نقطه پایانی زیر می توانید اشتراک فشار مرتبط با رمز ثبت نام خود را به روز کنید:

 https://iid.googleapis.com/v1/web/iid/REGISTRATION_TOKEN:refresh

مولفه های

  • مجوز: Bearer <access_token> . این پارامتر را در هدر تنظیم کنید.
  • Crypto-Key: p256ecdsa=APPLICATION_PUBLIC_KEY . این پارامتر را در هدر تنظیم کنید.
  • بدنه درخواست: PushSubscription.toJson() . اشتراک فشار را بدون تجزیه به بدنه HTTP منتقل کنید. محتوا با رمزگذاری W3C PushSubscription مطابقت دارد.

نتایج

در صورت موفقیت، تماس وضعیت HTTP 200 و یک نشانه ثبت نام را برمی گرداند. این ممکن است همان نشانه ای باشد که در درخواست ارسال کرده اید یا یک توکن جدید.

HTTP 200 OK
{
 "token":"KctODamlM4:CKrh_PC...cl"
}

نمونه درخواست POST

 https://iid.googleapis.com/v1/web/iid/KctODamlM4:CKrh_PC...cl:refresh
 Content-Type:application/json
 Authorization:Bearer ya29.ElqKBGN2Ri_Uz...HnS_uNreA
 Crypto-Key:p256ecdsa=BFv5XHxdkZgpQzCb-...8uI42kf4A4USEIMo
 {
   "endpoint": "https://fcm.googleapis.com/fcm/send/dS4xerbSlqU:APb...aRs4QP",
   "keys": {
         "auth": "7cdY...xxjwz46Q"",
         "p256dh": "BH7xPjScJe...z9lbIZDmOV_c"
    }
 }

نتیجه مثال

 HTTP 200 OK
 {
  "token":"KctODamlM4:CI2k_HHw...3P1"
 }

اشتراک های فشار را حذف کنید

درخواست DELETE جزئیات اشتراک push را از پایگاه داده FCM حذف می کند. همچنان می توانید با استفاده از پروتکل Push API پیام ها را در برنامه وب خود دریافت کنید.

برای حذف اشتراک Push، درخواست DELETE را به آدرس زیر ارسال کنید:

 https://iid.googleapis.com/v1/web/iid/REGISTRATION_TOKEN

مثال درخواست DELETE

 https://iid.googleapis.com/v1/web/iid/KctODamlM4:CI2k_HHw...3P1
 Authorization:Bearer ya29.ElqKBGN2Ri_Uz...HnS_uNreA

نتیجه مثال

 HTTP 200 OK {}

پاسخ های خطا

تماس‌های API سرور Instance ID کدهای خطای HTTP زیر را برمی‌گرداند:

  • HTTP status 400 (Bad request) - پارامترهای درخواست موجود نیستند یا نامعتبر هستند. برای اطلاعات دقیق پیام های خطا را بررسی کنید.
  • HTTP status 401 (Unauthorized) - سرصفحه مجوز نامعتبر است.
  • HTTP status 403 (Forbidden) - سرصفحه مجوز با authorizedEntity مطابقت ندارد.
  • HTTP status 404 (Not found) - مسیر HTTP یا کد IID نامعتبر یافت نشد. برای اطلاعات دقیق پیام های خطا را بررسی کنید.
  • HTTP status 503 (Service unavailable) - سرویس در دسترس نیست. درخواست را با عقب نشینی نمایی دوباره امتحان کنید.