Обзор ресурсов API. Руководство разработчика

Интеграция API Яндекс.

Оглавление

API открывает доступ к данным Яндекс.Вебмастера о сайтах. (https://yandex.ru/dev/webmaster/)

Данные в Вебмастере могут отличаться от данных Подбора слов (Wordstat) и Метрики!

1. Регистрация — нужен аккаунт любого из сервисов Яндекс. Например почта — https://mail.yandex.ru.

2. Зарегистрировать новое приложение — https://oauth.yandex.ru/client/new.

Чтобы начать работу с API Яндекс.Вебмастера, компания должна заключить с Яндексом соглашение в установленной форме и получить client_id в системе авторизации Яндекса oauth.yandex.ru.

Без client_id использование API невозможно.

В дальнейшем оно нам потребуется, чтобы получать токены пользователей, сайты которых мы хотим мониторить.

Заходим в только что созданное приложение, получаем «id приложения» и «пароль приложения»:

Результат регистрации приложения:

ID: 6cbc6303d4c147e697303c1fca9906c9

Пароль: __________________________

Callback URL: https://oauth. yandex.ru/verification_code

Где, ID – это client_id=6cbc6303d4c147e697303c1fca9906c9.

3. Получить токен через код подтверждения (https://yandex.ru/dev/oauth/doc/dg/reference/web-client-docpage/).

URL для запроса токена. https://oauth.yandex.ru/authorize?response_type=token&client_id=6cbc6303d4c147e697303c1fca9906c9

Результат: AgAAAAAEvkq-___________________________

Альтернативный вариант.

Идентификатор доступен в https://oauth.yandex.ru/ (нажмите на название приложения, чтобы открыть его свойства).

4. Кроме этого, при обращении к ресурсам API необходимо указывать ID пользователя — нужен для вызова любых ресурсов API (https://yandex.ru/dev/webmaster/doc/dg/reference/user-docpage/).

Его можно получить в начале работы с помощью вызова ресурса user.

URL запроса: https://api.webmaster.yandex.net/v4/user

Тип запроса: GET 

В Headers запроса необходимо указать ключ Authorization с значением  OAuth ________________________.

Где OAuth .. – это токен.

Результат:

{
    "user_id": 79579838
}

На данном этапе получены все параметры авторизации. Теперь можно работать с API запросами.

Документация — Обзор ресурсов API : https://yandex.ru/dev/webmaster/doc/dg/concepts/getting-started-docpage/.

API Яндекс.Вебмастера доступен для идентифицированных пользователей по адресу: https://api.webmaster.yandex.net.

Документация: https://yandex.ru/dev/webmaster/doc/dg/reference/host-search-queries-popular-docpage/

Формат запроса:

Тип запроса: GET

Кодировка: UTF-8.

Формат ответа: JSON.

URL запроса: 

https://api.webmaster.yandex.net/v4/user/{user-id}/hosts/{host-id}/search-queries/popular?order_by= & [query_indicator=]& [date_from=] & [date_to=]

Параметры query_indicator – можно написать несколько в одном запросе.

Пример – реальный запрос с перечислением всех индикаторов для отображения запросов.

https://api.webmaster.yandex.net/v4/user/79579838/hosts/https:falcon.web-automation.ru:443/search-queries/popular?order_by=TOTAL_SHOWS&query_indicator=TOTAL_SHOWS&date_from=2020-01-01&date_to=2020-12-31&query_indicator=TOTAL_CLICKS&query_indicator=AVG_SHOW_POSITION&query_indicator=AVG_CLICK_POSITION

Ответ запроса преобразуется из формата JSON в таблицу вида.

Аналогичным образом реализованы несколько других запросов, указанных в документации.

Результат:

Приведен с сокращениями.

{
    "count": 2791,
    "queries": [
        {
            "query_id": "4655b69c239b6462",
            "query_text": "cms для маркетплейса",
            "indicators": {
                "TOTAL_SHOWS": 92.
 
  0,
                "TOTAL_CLICKS": 8.0,
                "AVG_SHOW_POSITION": 7.521739130434782,
                "AVG_CLICK_POSITION": 6.375
            }
        },
        {
            "query_id": "f8de4510bbd8a622",
            "query_text": "скрипт маркетплейса",
            "indicators": {
                "TOTAL_SHOWS": 71.0,
                "TOTAL_CLICKS": 25.0,
                "AVG_SHOW_POSITION": 4.549295774647887,
                "AVG_CLICK_POSITION": 4.52
            }
        },
…
        {
            "query_id": "dde486b6f18ac2c3",
            "query_text": "манго офис коллтрекинг видео",
            "indicators": {
                "TOTAL_SHOWS": 2.0,
                "TOTAL_CLICKS": 0.0,
                "AVG_SHOW_POSITION": 13.0,
                "AVG_CLICK_POSITION": null
            }
        }
    ],
    "date_from": "2020-01-01",
    "date_to": "2020-06-20"
}

CREATE PROCEDURE [dbo].[api_yaWebmasterQueriesPopularCounters_request]
	@parameters ExtendedDictionaryParameter READONLY,  -- входящие параметры для внутренней обработки (используйте Key, Value2)
	@username nvarchar(32)  -- текущий пользователь.
  AS
BEGIN
-- ВХ.ПАРАМ. -- АВТОРИЗАЦИЯ
DECLARE @token nvarchar(MAX)
SET     @token = N'OAuth AgAAAAAEvkq-_______________________' -- Authorization
DECLARE @user_id nvarchar(MAX) -- Тип: int64. ID пользователя. Необходим для вызова любых ресурсов API Яндекс.Вебмастера.
SET     @user_id = N'79579838' -- N'"user_id": 79579838' --
DECLARE @host_id nvarchar(MAX) -- Тип: host id (string). ID сайта.
SET     @host_id = N'https:falcon.web-automation.ru:443'
-- Параметры запроса
DECLARE @order_by nvarchar(100)	--  ? order_by= 			-- TOTAL_SHOWS 	Количество показов. / TOTAL_CLICKS 	Количество кликов.
SET     @order_by = N'TOTAL_SHOWS'
DECLARE @query_indicator nvarchar(100)	--  & [query_indicator=]	-- TOTAL_SHOWS 	Количество показов. / TOTAL_CLICKS 	Количество кликов. / AVG_SHOW_POSITION 	Средняя позиция показа. / AVG_CLICK_POSITION 	Средняя позиция клика.
SET     @query_indicator = N'TOTAL_SHOWS'
-- ! ВСЕ_ПАРАМЕТРЫ - можно получить одним запросом !
DECLARE @query_indicator2 nvarchar(100) = NULL
SET     @query_indicator2 = N'TOTAL_CLICKS'
DECLARE @query_indicator3 nvarchar(100) = NULL
SET     @query_indicator3 = N'AVG_SHOW_POSITION'
DECLARE @query_indicator4 nvarchar(100) = NULL
SET     @query_indicator4 = N'AVG_CLICK_POSITION'
DECLARE @date_from nvarchar(10)	 --  & [date_from=] -- 2020-01-01 -- ГГГГ-ММ-ЧЧ -- 23 	ISO8601 	гггг-мм-дд
SET     @date_from = CONVERT ( nvarchar(10) , GETDATE() - 30 , 23 )   -- минус 1 месяц от текущей даты
DECLARE @date_to nvarchar(10)	 --  & [date_to=] -- 2020-12-31 -- ГГГГ-ММ-ЧЧ -- 23 	ISO8601 	гггг-мм-дд
SET     @date_to = CONVERT ( nvarchar(10) , GETDATE() , 23 )
DECLARE @apiUrl nvarchar(max) = '' 		-- Финальная строка для отправки -- @apiStr -- ФАКТИЧЕСКИ ЭТО Url
-- SET     @apiUrl = 'https://api. 
  webmaster.yandex.net/v4/user/79579838/hosts/https:falcon.web-automation.ru:443/search-queries/popular?order_by=TOTAL_SHOWS&query_indicator=TOTAL_SHOWS&date_from=2020-01-01&date_to=2020-12-31&query_indicator=TOTAL_CLICKS&query_indicator=AVG_SHOW_POSITION&query_indicator=AVG_CLICK_POSITION'
SET     @apiUrl = 'https://api.webmaster.yandex.net/v4/user/'+@user_id
                                                             +'/hosts/'+ @host_id
                                                             +'/search-queries/popular?order_by='+@order_by
                                                             +'&query_indicator='+@query_indicator
                                                             +'&date_from='+@date_from
                                                             +'&date_to='+@date_to
                                                             + IIF (  @query_indicator2 IS NOT NULL, +'&query_indicator='+@query_indicator2, '' )
                                                             + IIF (  @query_indicator2 IS NOT NULL, +'&query_indicator='+@query_indicator3, '' )
                                                             + IIF (  @query_indicator2 IS NOT NULL, +'&query_indicator='+@query_indicator4, '' )
    -- ОТЛАДКА
	 insert into as_trace ( header, text, username, code , created )   values( '@apiUrl', @apiUrl , @username, 'api_yaWebmasterQueriesPopularCounters_request' , GETDATE() )
    -- Постоянные табблицы - 1 - dbo.  api_yaWebmasterSessions - Журнал Запусков (дата + параметры) - 2 - api_yaWebmasterSessionsData - результат
    insert into dbo.api_yaWebmasterSessions ( created , userСreator , requestPROCEDURE
                                             	, apiCommonName		  -- убрать из измени проц. начало api_ ... и конец ... _request
                                                , date_from	  , date_to
                                             	, apiUrl )
    values(  GETDATE() ,  @username , 'api_yaWebmasterQueriesPopularCounters_request'
                                    , 'yaWebmasterQueriesPopularCounters'          -- убрать из измени проц. начало api_ ... и конец ... _request
                                    , @date_from , @date_to
                					, @apiUrl  )
	-- SELECT 1  Msg, Result, Url (адрес, куда будет идти запрос)
	select '' Msg, 1 Result
          , @apiUrl  Url
	-- SELECT 2 PARAMETERS - параметры, которые будут передаваться во внешний источник
    select 'Authorization' name
         , 'OAuth AgAAAAAEvkq-_____________________________' value  -- @token
         , 'header' AS [type] -- form (в форме передается), header (в http headers), get запросы передавайте прямо в URL
END

CREATE PROCEDURE [dbo]. [api_yaWebmasterQueriesPopularCounters_response]
	@response nvarchar(max),
	@parameters ExtendedDictionaryParameter READONLY,  -- входящие параметры для внутренней обработки (используйте Key, Value2 - те же что и на request)
	@username nvarchar(32)
AS
BEGIN
   -- ОТЛАДКА
   	insert into as_trace ( header, text, username, code , created )  values( 'LEN @response ', LEN ( @response ) , @username, 'api_yaWebmasterQueriesPopularCounters_response' , GETDATE() )
	insert into as_trace ( header, text, username, code , created )  values( '@response - 1    , 1024 ', SUBSTRING ( @response , 1    , 1024 ) , @username, 'api_yaWebmasterQueriesPopularCounters_response' , GETDATE() )
-- ! Преобразование - заменить одиночную кавычку на двойную ! - иначе это будет обрыв строки (конец стркои) в середине текста !
-- "eckmar's marketplace script v2.0",
--        !
DECLARE @json1 nvarchar(max)
SET     @json1 = REPLACE ( @response  , '''' , '''''' )
-----------------------------------------------------------------------------------------------------------------
-- Постоянные табблицы - 1 - dbo. api_yaWebmasterSessions - Журнал Запусков (дата + параметры) - 2 - api_yaWebmasterSessionsData - результат
-- Определение номера сесии, считаем, что это последняя запись в журнале запусков для текущего пользователя
DECLARE @maxSessionID int = 0
SELECT  @maxSessionID = ISNULL( MAX( id ), 0) FROM dbo.api_yaWebmasterSessions WHERE userСreator = @username AND apiCommonName = 'yaWebmasterQueriesPopularCounters'
-- Основной запрос
-- ВСТАВКА ДАННЫХ
INSERT INTO   dbo.api_yaWebmasterSessionsData ( sessionID, countResult	, date_from, date_to
                     , query_id , query_text, TOTAL_SHOWS, TOTAL_CLICKS	, AVG_SHOW_POSITION, AVG_CLICK_POSITION )
SELECT @maxSessionID AS sessionID
	 --
     , TRY_CAST ( JSON_VALUE(@json1, '$.count')	AS INT ) AS countResult
     , JSON_VALUE(@json1, '$.date_from') AS	date_from		-- "date_from": "2020-01-01",
     , JSON_VALUE(@json1, '$.date_to')	 AS date_to			-- "date_to": "2020-06-14"
	 --
	 , Query.query_id, Query.query_text
     , ISNULL( Query.TOTAL_SHOWS, 0) , ISNULL( Query. TOTAL_CLICKS, 0) , ISNULL( Query.AVG_SHOW_POSITION, 0) , ISNULL( Query.AVG_CLICK_POSITION, 0)
FROM OPENJSON(@json1, N'$.queries') -- Зашли в массив queries , далее в WITH считаем , что адреса уже внути массива queries
WITH (
      query_id      VARCHAR(200)    N'$.query_id'
    , query_text    VARCHAR(200)    N'$.query_text'
	, TOTAL_SHOWS   		decimal(18, 2)  N'$.indicators.TOTAL_SHOWS' -- VARCHAR(200)
	, TOTAL_CLICKS   		decimal(18, 2)  N'$.indicators.TOTAL_CLICKS'
	, AVG_SHOW_POSITION 	decimal(18, 2)  N'$.indicators.AVG_SHOW_POSITION'
	, AVG_CLICK_POSITION    decimal(18, 2)  N'$.indicators.AVG_CLICK_POSITION'
    ) AS Query
-----------------------------------------------------------------------------------------------------------------
--  табл. с данными - dbo.api_yaWebmasterSessionsData / строк - ***
DECLARE @isExistTable int = 0
DECLARE @countTableRecords int = 0
SELECT  @isExistTable = ISNULL( object_id('api_yaWebmasterSessionsData') , 0 )
IF @isExistTable > 0 SELECT @countTableRecords = ISNULL( count(*) , 0 ) FROM dbo. api_yaWebmasterSessionsData WHERE sessionID = @maxSessionID
	-- SELECT 1
	select 'Табл. с данными - dbo.api_yaWebmasterSessionsData '
           + IIF ( @isExistTable = 0
                    , 'не заполнена!'
                    , 'заполнена, записей - '+ TRY_CAST ( @countTableRecords AS nvarchar) +'. Сесиия - '+ TRY_CAST ( @maxSessionID AS nvarchar)
                 )  AS  Msg
          , 1 Result
          , @response Response
	-- SELECT 2 Внешние действия
END

Приведенные ниже запросы API работают по тому же принципу.

Falcon Space — функциональная веб-платформа разработки на узком стеке MS SQL/Bootstrap. Вводная по Falcon Space

Насколько полезной была статья?

Google поиск по нашей документации

alexreznikov/webmaster.api — Packagist

Библиотека Yandex Webmaster Api v3

Сопровождающие

Детали

github.com/alexeyreznikov/webmaster.api

Домашняя страница

Источник

Устанавливает: 18

иждивенцы: 0

Предлагает: 0

Безопасность: 0

Звезды: 0

Наблюдатели: 1

Вилки: 28

2,0 2020-09-19 14:41 UTC

MPL-2. 0 23afa1dc0b42157e0a9416c768d0be32220781cd

 {
    "требовать": {
        ...
        "yandex/webmaster.api": "dev-мастер"
        ...
    }
} 

 php composer.phar требуют yandex/webmaster.api "dev-master"
 

 ...
    "хранилища": [
        {
            "тип": "ВКС",
            "url": "https://github. com/yandex/webmaster.api"
        }
    ]
    ...