المتطلبات الأساسية لواجهة Indexing API

قبل بدء استخدام Indexing API، عليك اتّخاذ بعض الإجراءات، إذا لم يسبق لك اتّخاذها:

• إنشاء مشروع لعميلك
• إنشاء حساب خدمة
• إضافة حساب الخدمة كمالك للموقع الإلكتروني
• الحصول على رمز الدخول

إنشاء مشروع لعميلك

قبل إرسال طلبات إلى واجهة Indexing API، عليك تزويد Google بمعلومات حول عميلك وتفعيل إمكانية الوصول إلى واجهة برمجة التطبيقات. ويمكنك إجراء ذلك عن طريق الاستعانة بوحدة التحكم في Google API لإنشاء مشروع، وهو مجموعة معرّفة من الإعدادات ومعلومات الدخول إلى واجهة برمجة التطبيقات، ولتسجيل تطبيقك.

لبدء استخدام Indexing API، عليك أولاً استخدام أداة الإعداد التي تقدّم لك إرشادات خلال عملية إنشاء المشروع في وحدة التحكم في Google API وتفعيل واجهة برمجة التطبيقات وإنشاء بيانات الاعتماد.

إنشاء حساب الخدمة

1. افتح صفحة حسابات الخدمة. اختَر مشروعًا إذا طُلب منك ذلك.
2. انقر على إنشاء حساب للخدمة ثم أدخِل اسمًا ووصفًا لحساب الخدمة. يمكنك استخدام معرّف حساب الخدمة التلقائي أو اختيار معرّف فريد مختلف. وعند الانتهاء من ذلك، انقر على إنشاء.
3. قسم أذونات حساب الخدمة (اختيارية) التالي غير مطلوب. انقر على متابعة.
4. انتقِل إلى القسم إنشاء مفتاح في أسفل شاشة منح المستخدمين صلاحية الوصول إلى حساب الخدمة هذا. انقر على إنشاء مفتاح.
5. في اللوحة الجانبية التي تظهر، اختَر التنسيق الذي تريده للمفتاح: وننصح باختيار: JSON.
6. انقر على إنشاء. يتم إنشاء زوج المفتاح العام/الخاص وتنزيله على جهازك، وهو النسخة الوحيدة من هذا المفتاح. للحصول على معلومات عن طريقة التخزين الآمن للمفتاح، يُرجى مراجعة إدارة مفاتيح حساب الخدمة.
7. انقر على إغلاق في مربّع الحوار تم حفظ المفتاح الخاص على الكمبيوتر، ثم انقر على تم للرجوع إلى جدول حسابات الخدمة.

إضافة حساب الخدمة الخاص بك بصفتك مالكًا للموقع الإلكتروني

إليك الخطوات التي يجب اتّباعها لإضافة حساب الخدمة كمالك للموقع الإلكتروني:

1. عليك أولاً إثبات ملكيتك للموقع الإلكتروني باستخدام Search Console.
2. عليك بعد ذلك إضافة حساب الخدمة كمالك.

1. إثبات ملكيتك للموقع الإلكتروني

يجب إثبات ملكية موقعك الإلكتروني باستخدام Search Console بأي طريقة تتيحها الخدمة. يمكنك إنشاء موقع إلكتروني على النطاق (example.com) أو موقع إلكتروني يبدأ بعنوان URL (https://example.com أو https://example.com/some/path/) لتمثيل موقعك الإلكتروني. (تُعرف باسم مواقع إلكترونية في Search Console).

2. منح دور المالك لحساب الخدمة الخاص بك

أضِف بعد ذلك حساب الخدمة الخاص بك كمالك (مفوَّض) للموقع الإلكتروني:

1. افتح مجموعة خدمات مشرفي المواقع.
2. انقر على الموقع الإلكتروني الذي أثبتّ ملكيته.
3. في قائمة المالك المعتمَد، انقر على إضافة مالك.
4. أدخِل البريد الإلكتروني لحساب الخدمة بصفتك المالك المفوَّض. يمكنك العثور على عنوان البريد الإلكتروني الخاص بحساب الخدمة في موضعَين:
   • حقل client_email في المفتاح الخاص بترميز JSON والذي نزّلته عندما أنشأت مشروعك.
   • عمود معرّف حساب الخدمة في عرض حسابات الخدمة في Developers Console.
   يكون تنسيق عنوان البريد الإلكتروني على النحو التالي:
   [e-mail]
   على سبيل المثال: [e-mail].

الحصول على رمز الدخول

يجب المصادقة على كل طلب من Indexing API باستخدام رمز OAuth المميز الذي تحصل عليه مقابل مفتاحك الخاص. ويبقى كل رمز مميّز صالحًا لفترة زمنية محددة. وتوفر Google مكتبات عميل واجهة برمجة التطبيقات للحصول على رموز OAuth المميزة الخاصة بعدد من اللغات.

المتطلبات

عند إرسال طلب إلى Indexing API، يجب أن يستوفي طلبك الشروط التالية:

1. استخدام https://www.googleapis.com/auth/indexing كنطاق
2. استخدام إحدى نقاط النهاية الموضّحة في استخدام واجهة برمجة التطبيقات
3. تضمين رمز الدخول إلى حساب الخدمة
4. تحديد نص الطلب بالشكل الموضّح في استخدام واجهة برمجة التطبيقات

أمثلة

توضح الأمثلة التالية طريقة الحصول على رمز OAuth مميز للدخول:

لغة Python

يمكن الحصول على رمز OAuth مميز باستخدام مكتبة عميل واجهة Google API للغة Python:

from oauth2client.service_account import ServiceAccountCredentials
import httplib2

SCOPES = [ "https://www.googleapis.com/auth/indexing" ]
ENDPOINT = "https://indexing.googleapis.com/v3/urlNotifications:publish"

# service_account_file.json is the private key that you created for your service account.
JSON_KEY_FILE = "service_account_file.json"

credentials = ServiceAccountCredentials.from_json_keyfile_name(JSON_KEY_FILE, scopes=SCOPES)

http = credentials.authorize(httplib2.Http())

# Define contents here as a JSON string.
# This example shows a simple update request.
# Other types of requests are described in the next step.

content = """{
  \"url\": \"http://example.com/jobs/42\",
  \"type\": \"URL_UPDATED\"
}"""

response, content = http.request(ENDPOINT, method="POST", body=content)

لغة Java

يمكن الحصول على رمز OAuth مميز باستخدام مكتبة عميل واجهة Google API للغة Java:

String scopes = "https://www.googleapis.com/auth/indexing";
String endPoint = "https://indexing.googleapis.com/v3/urlNotifications:publish";

JsonFactory jsonFactory = new JacksonFactory();

// service_account_file.json is the private key that you created for your service account.
InputStream in = IOUtils.toInputStream("service_account_file.json");

GoogleCredential credentials =
  GoogleCredential.fromStream(in, this.httpTransport, jsonFactory).createScoped(Collections.singleton(scopes));

GenericUrl genericUrl = new GenericUrl(endPoint);
HttpRequestFactory requestFactory = this.httpTransport.createRequestFactory();

// Define content here. The structure of the content is described in the next step.
String content = "{"
  + "\"url\": \"http://example.com/jobs/42\","
  + "\"type\": \"URL_UPDATED\","
  + "}";

HttpRequest request =
  requestFactory.buildPostRequest(genericUrl, ByteArrayContent.fromString("application/json", content));

credentials.initialize(request);
HttpResponse response = request.execute();
int statusCode = response.getStatusCode();

لغة PHP

يمكن الحصول على رمز OAuth مميز باستخدام مكتبة عميل واجهة Google API للغة PHP:

require_once 'google-api-php-client/vendor/autoload.php';

$client = new Google_Client();

// service_account_file.json is the private key that you created for your service account.
$client->setAuthConfig('service_account_file.json');
$client->addScope('https://www.googleapis.com/auth/indexing');

// Get a Guzzle HTTP Client
$httpClient = $client->authorize();
$endpoint = 'https://indexing.googleapis.com/v3/urlNotifications:publish';

// Define contents here. The structure of the content is described in the next step.
$content = '{
  "url": "http://example.com/jobs/42",
  "type": "URL_UPDATED"
}';

$response = $httpClient->post($endpoint, [ 'body' => $content ]);
$status_code = $response->getStatusCode();

Node.js

يمكن الحصول على رمز OAuth مميز باستخدام مكتبة عميل Node.js:

var request = require("request");
var { google } = require("googleapis");
var key = require("./service_account.json");

const jwtClient = new google.auth.JWT(
  key.client_email,
  null,
  key.private_key,
  ["https://www.googleapis.com/auth/indexing"],
  null
);

jwtClient.authorize(function(err, tokens) {
  if (err) {
    console.log(err);
    return;
  }
  let options = {
    url: "https://indexing.googleapis.com/v3/urlNotifications:publish",
    method: "POST",
    // Your options, which must include the Content-Type and auth headers
    headers: {
      "Content-Type": "application/json"
    },
    auth: { "bearer": tokens.access_token },
    // Define contents here. The structure of the content is described in the next step.
    json: {
      "url": "http://example.com/jobs/42",
      "type": "URL_UPDATED"
    }
  };
  request(options, function (error, response, body) {
    // Handle the response
    console.log(body);
  });
});

بالإضافة إلى عرض طريقة الحصول على الرمز المميز، توضح هذه الأمثلة الموضع الذي يمكنك فيه إضافة نص رسالة الطلب. لمزيد من المعلومات عن أنواع عمليات الاستدعاء التي يمكنك إجراؤها وبنية نصوص رسائل عمليات الاستدعاء هذه، يُرجى مراجعة استخدام واجهة برمجة التطبيقات.