المتطلبات الأساسية "لواجهة برمجة التطبيقات للفهرسة"

قبل بدء استخدام "واجهة برمجة التطبيقات للفهرسة"، عليك إجراء بعض الأمور، إذا لم يسبق لك إجراؤها:

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

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

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

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

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

الخطوات التالية ضرورية فقط إذا كنت تريد منح صلاحية على مستوى نطاق G Suite لحساب الخدمة.

  1. حدِّد موضع حساب الخدمة المُنشأ حديثًا في الجدول. ضمن الإجراءات، انقر على more_vert ثم تعديل.
  2. ضمن تفاصيل حساب الخدمة، انقر على expand_more عرض التفويض على مستوى النطاق، تأكّد من وضع علامة في مربّع الاختيار تفعيل التفويض على مستوى نطاق G Suite.
  3. إذا لم تكن قد ضبطت إعداد شاشة موافقة OAuth في تطبيقك، عليك ضبطه قبل أن تتمكَّن من تفعيل التفويض على مستوى النطاق. اتبع التعليمات التي تظهر على الشاشة لإعداد شاشة موافقة OAuth، ثم كرر الخطوات السابقة وأعد وضع علامة في مربّع الاختيار.
  4. انقر على حفظ لتحديث حساب الخدمة، ثم ارجع إلى جدول حسابات الخدمة. يظهر عمود جديد باسم التفويض على مستوى النطاق. انقر على عرض معرّف العميل للحصول على معرّف العميل وتسجيله.

إثبات ملكية الموقع في Search Console

في هذه الخطوة، يمكنك التأكُّد من تحكمك في موقع الويب.

لإثبات ملكية موقعك:

  1. اتبِّع الخطوات المقترحة لإثبات ملكية موقعك الإلكتروني.
  2. بعد إثبات ملكية موقعك الإلكتروني، افتح Search Console.
  3. انقر على الموقع الذي اثبتَّ ملكيته.
  4. اختَر تفاصيل إثبات الملكية من خلال رمز ترس "الإعدادات" بجانب الموقع الذي تم إثبات ملكيته.
  5. ضمن مالكون تم إثبات ملكيتهم، انقر على إضافة مالك.
  6. أضِف عنوان البريد الإلكتروني الخاص بحساب الخدمة بصفتك مالك الموقع الإلكتروني. ويمكنك العثور على عنوان البريد الإلكتروني الخاص بحساب الخدمة في مكانين:
    • حقل client_email في المفتاح الخاص بترميز JSON الذي تم تنزيله عند إنشاء مشروعك.
    • عمود معرّف حساب الخدمة في عرض حسابات الخدمة في Developer Console.

    يكون تنسيق عنوان البريد الإلكتروني على النحو التالي:

    my-service-account@project-name.google.com.iam.gserviceaccount.com

    على سبيل المثال، "my-service-account@test-project-42.google.com.iam.gserviceaccount.com".

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

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

المتطلبات

عند إرسال طلب إلى "واجهة برمجة التطبيقات للفهرسة"، يجب أن يستوفي طلبك الشروط التالية:

  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 مميَّز باستخدام مكتبة برامج واجهة برمجة التطبيقات للغة 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 مميَّز باستخدام مكتبة برامج واجهة برمجة التطبيقات للغة 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);
  });
});

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