Иногда лучше всего то, что вышло из коробки.

Шум (

Я думал, что ответ — все отрезать?

Колеса (

Не покупайте сомнительные металлы.

Happy Medium (

Проведите собственное исследование.

For The Daily (

Тормозная жидкость и дворники.

Важные вещи (

Не могу согласиться, приятель.

Пока мы в теме (

Серьезно.

Масляные фильтры (

Добраться до источника.

Дорого = / = Лучше (

Но если вы действительно верите, что дорого всегда лучше, что вы здесь делаете?

Octane Booster (

Есть спектр.

93 Октан (

Ага! Нитвиц!

Не тратьте деньги зря (

Следите за этим.

Тормозные диски (

В моем минивэне роторы просверлены и проделаны.

Портал разработчиков Bazaarvoice | Review

API Bazaarvoice Response позволяет программно управлять ответами на отзывы. Чтобы узнать больше, перейдите на домашнюю страницу документации Response API.

На этой странице описан ресурс Review.

Запрос

В следующем блоке кода показан пример запроса. Перейдите в раздел Инструменты, чтобы получить доступ к интерактивным инструментам и приложениям, которые помогут вам работать с Response API.

ПОЛУЧИТЬ https: // [stg.] Api.bazaarvoice.com/response/v1/clientResponses/ {responseGuid} / review? Passkey = {PRIVACY_API_PASSKEY} HTTP / 1. 1

Авторизация: предъявитель {ACCESS_TOKEN}
…
 



Старые приложения могут использовать https: // [stg.] Api.bazaarvoice.com/ contentmanagement в качестве базового URL-адреса для Response API вместо https: // [stg.] Api.bazaarvoice.com / ответ . URL-адрес Contentmanagement устарел.Однако Bazaarvoice продолжит поддерживать приложения, использующие URL-адрес Contentmanagement , до дальнейшего уведомления.

Эллипсы (…) в приведенном выше примере указывают на то, что ваше приложение может генерировать другие заголовки.

Параметры

Ответ

Заголовок

Статус HTTP 200 указывает на успех. Другие значения заголовка задокументированы в обзоре.

Кузов

Успешный ответ будет содержать объект JSON в теле. Ниже показано типичное успешное создание ответа клиента:

{
    "данные": {
        "тип": "обзор",
        "id": "75266",
        "clientName": "someClientName"
    },
    "links": {
        "self": "https: // [stg. ] api.bazaarvoice.com/response/v1/clientResponses/XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX/relationships/review ",
        "related": "https: // [stg.] api.bazaarvoice.com/response/v1/clientResponses/XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXX/review"
    }
}
 

Синтаксис ответа соответствует спецификации JSON API, предоставляя данных , ссылок и связей узлов.

Ошибки

Подробное описание и решение ошибок Response API см. В разделе «Устранение неполадок».

community / api-review-process.md at master · kubernetes / community · GitHub

Контакт

Чтобы сохранить удобство использования и согласованность в основных API Kubernetes, изменения и дополнения требуют надзора. Процесс проверки API предназначен для поддержания логической и функциональной целостности API с течением времени, единообразие пользовательского опыта и способность ранее написанных инструментов работать с новыми API. По возможности, процесс проверки API должен помогать отправителям изменений следовать установленным соглашениям. а не просто отвергать без причины.

Поскольку пропускная способность рецензента ограничена, процесс обеспечивает приоритетное отставание. Хотя это означает, что некоторые изменения могут быть отложены в пользу других более приоритетных, это поможет поддерживать критическую скорость проекта, прозрачность и равновесие. В идеале те, чей приоритет проверки API смещен таким образом, чтобы это повлияло на выпуск, будут заранее уведомлены рецензентами.

• Обеспечить прозрачный, легко управляемый процесс, чтобы все стороны понимали свои роли, обязанности и ожидания.

• Защита API Kubernetes от разрушительных, непоследовательных или дестабилизирующих изменений

• Оптимизация опыта пользователей, использующих наши API, с учетом усилий требуется от авторов API.

• Уважайте, максимизируйте и расширяйте полосу пропускания рецензента

• Интеграция с обычным процессом проверки, добавление как можно меньших накладных расходов, связанных с проверкой API

Обязательный

Ожидается, что устройство смены отправит изменения на проверку API, и изменение заблокировано на одобрении проверяющего API. Как правило, все, что считается частью «ядра Kubernetes», требует обязательной проверки API.В приведенном ниже списке перечислены основные API Kubernetes:

• Все реализации API (включая альфа-версии), которые являются частью ядра Kubernetes, должны быть проверены, включая CRD, чтобы взаимодействие с пользователем во всей экосистеме Kubernetes было согласованным.

• github.com/kubernetes/kubernetes, а также любые проекты kubernetes- * org, от которых он зависит, должны быть проверены.

• API в стиле Kubernetes, использующий * .k8s.io или * .kubernetes.io имя, например «storage.k8s.io».

• «Критических» или других «высокоинтегрированных» API, таких как наши точки расширения в узле, apiserver и контроллерах. Сюда входят CSI, CNI, CRI и CPI.

Добровольное

Добровольные проверки применяются к непрофильным API, которые не соответствуют обязательным требованиям, перечисленным выше. Changer может запросить проверку, или стороннее лицо может назначить API для проверки. Комментарии к обзору считаются рекомендациями.

• SIG спонсировал API на основе CRD вне ядра, которые используют пространство имен «* .x-k8s.io».

• Подпроекты, спонсируемые SIG, которые создают API (включая CRD) вне групп API * .k8s.io или * .kubernetes.io и предназначены для работы с kubectl и / или kube-apiserver. (цель состоит в том, чтобы обеспечить единообразное взаимодействие с пользователем во всей экосистеме Kubernetes)

Какие части PR являются «изменениями API»?

• «API ресурсов» включают определение версионных данных (pkg / apis / / v / types.go или OpenAPI для CRD), проверка (pkg / apis / * / validation.go или OpenAPI для CRD).

• Конфигурационные файлы, флаги и аргументы командной строки являются частью наших пользовательских интерфейсов и API-интерфейсов, работающих со сценариями, и их необходимо проверять.

• Встроенные API-интерфейсы kube-apiserver

• Форматы запросов / ответов Webhooks в kube-apiserver

• HTTP API в kubelet

• , на которые не распространяются какие-либо другие стандарты (например,грамм. CSI и CNI API будут переданы этим органам по стандартизации)

0. Заявители должны заполнить контрольный список предварительной проверки:

   • Цель предлагаемого изменения согласована с соответствующими владельцами подпроектов и / или руководителями SIG
   • Для изменений в kubernetes- * org создана проблема KEP и отслеживания в kubernetes- * org:
     • Любой новый тип ресурса
     • Любая новая версия стабильного API
     • Любые новые функции, добавленные к стабильному API в соответствии с определением SIG Architecture и API Reviewers
     • Любое изменение значения, проверки или поведения поля
   • Существующие соглашения API (и рекомендации по изменению API, если применимо) были прочитаны и соблюдены.

1. Запросите проверку API для PR или проблемы в kubernetes org, добавив метку api-review с комментарием / label api-review (запросы могут быть отменены с помощью комментария / remove-label api-review )

   • Если это обзор PR, реализующего уже рассмотренный дизайн / KEP, сослаться на утвержденный KEP и отметить любые различия между утвержденным дизайном и реализацией.

2. обзоров API отслеживаются на доске проекта по адресу https: // github.ru / orgs / kubernetes / projects / 13

   • Запрос Github для запрошенных обзоров, еще не включенных в проект:
   • Запрос Github для элементов в проекте, больше не требующих проверки:
   • Запросы регулярно сортируются утверждающими / рецензентами / модераторами API и добавляются в доску проекта, если предварительные требования были выполнены
   • Когда запросы добавляются на доску проекта, это отражается на боковой панели проблемы или PR вместе с текущим статусом (невыполнение, назначено, выполняется, выполнено)
   • Журнал и очередь проверки API общедоступны по адресу https: // github. ru / orgs / kubernetes / projects / 13

3. Задержка

   • Утверждающий или модератор изменит приоритет проблемы в невыполненной работе. Приоритет обзоров определяется по ряду факторов:
   • Нацелено ли изменение на текущую веху, конкретную будущую веху или не нацелено на нее
   • Уровень зрелости изменения (обычно GA> beta> alpha)
   • Обратная связь от руководителей SIG / руководителей подпроектов по относительным приоритетам
   • Является ли это первоначальной проверкой или повторной проверкой (или проверкой PR, реализующей уже проверенный API в KEP)
   • Размер / сложность изменения

4. Назначен

   • Утверждающий или модератор назначит утверждающего (или потенциально стремящегося рецензента — см. обучающих обзоров ниже, чтобы узнать о рабочем процессе начинающего рецензента)
   • Обзоры назначаются на основе возможностей рецензента и знания предметной области
   • Назначение рецензентов выполняется по самой проблеме / PR с использованием обычного метода / assign (без проблем работает с существующими запросами на панели мониторинга github / PR)
   • Все обзоры API, назначенные отдельному лицу, можно просматривать на доске проекта (пример), чтобы видеть статус, заказ и нагрузку на рецензентов

5. Выполняется / Утверждено / Запрошены изменения / Отклонено

   • Проверки проходят как обычная проверка KEP или PR.Возможные исходы:
   • Утверждение:
     • PR внедрения помечены тегом / lgtm / Approve и обычно объединяются
     • KEP PR, содержащие проекты API, также могут быть помечены тегом / lgtm / Approve , но должны явно указывать, предоставляется ли одобрение API. Это утверждение должно быть связано с последующим запросом обзора ТЗ реализации и должно ограничивать объем обзора реализации различиями между утвержденным дизайном и окончательной реализацией, проблемами, возникающими во время реализации, и правильностью реализации.
     • Утвержденная проблема заархивирована в доске проекта проверки, а метка api-review удалена.
   • Запрошенные изменения:
     • Комментарии или вопросы остаются по поводу PR или проблемы, и рецензент уведомляет отправителя
     • Рецензент перемещает проблему в раздел «Запрошенные изменения» на доске проекта проверки
     • После того, как запрошенные изменения внесены или получены ответы на вопросы, отправитель уведомляет проверяющего, который перемещает проблему обратно в «Выполняется».
     • По мере возможности, следует запрашивать и вносить полные наборы комментариев / изменений, чтобы избежать чрезмерных циклов туда-сюда.
   • Отклонено:
     • Если полностью отклонено, например «Пожалуйста, выполняйте эту работу вне организации Kubernetes» — объяснение того, почему изменение было отклонено — апелляции могут быть запрошены из списка рассылки api-Approvers ([email protected]), где модератор будет координировать последующие действия. вверх обзор. Если этот запрос приводит к другому отказу, дальнейшая апелляция не производится.
     • Отклоненная проблема помещается в доску проекта проверки, а метка api-review удаляется.

Просмотр сроков жизненного цикла

В идеале рецензирование должно происходить как можно быстрее, но это сильно зависит от доступности рецензента и пропускной способности. В целом можно ожидать следующий таймфрейм:

• время t: запрос на рассмотрение
• раз t + 1 неделя: с приоритетом и в очереди
• раз t + 3 недели: первая проверка завершена
• время t + 4 недели: последующая проверка завершена
• раз t + 6 недель: одобрено или отклонено

Время запросов на проверку API имеет значение.Чем больше изменение, тем больше времени должно быть предоставлено. Новые ресурсы API (известные как Kinds) могут потребовать значительно большего обдумывания, чем добавление отдельных полей. Проверки API, запрошенные слишком поздно в цикле выпуска, могут не завершиться вовремя для выпуска. Планируйте заранее. Кроме того, если вы меняете утвержденный API, вы должны проконсультироваться со списком [email protected], чтобы убедиться, что он по-прежнему соответствует уже предоставленным утверждениям. В этом случае с точки зрения процесса вы должны запросить новую проверку.

Роль модератора

Роль модератора укомплектована SIG Architecture и управляет невыполненной проверкой API от имени группы проверяющих. Они гарантируют, что обзоры будут завершены в разумные сроки, что информация верна и что будут применены соответствующие ярлыки состояния. Они также могут помочь расставить приоритеты для невыполненных работ или перемещать карточки по доске проекта. Их миссия — помочь рецензентам тратить большую часть своих усилий на выполнение рецензирования, а не на администрирование процесса.Они также могут работать с группой проверки, чтобы при необходимости запланировать очные сеансы проверки или обеспечить добавление проверки в повестку дня собрания SIG-Architecture.

Расширение пула проверяющих и утверждающих

В этом процессе есть два уровня полномочий. Рецензент и утверждающий. Рецензенты обладают опытом, чтобы полностью оценить и дать рекомендации, так что со стороны утверждающего требуются минимальные дополнительные усилия. Утверждающие наделены полномочиями по принятию окончательного решения по запросу, и их можно обжаловать только в порядке, указанном выше.

Чтобы стать официальным рецензентом, вы должны достичь высокого уровня понимания соглашений API, структуры проекта и базовой архитектуры. Лучший путь — изучить работы других начинающих рецензентов и утверждающих. После ознакомления с основными концепциями следует связаться с модератором, чтобы его подобрали наставник рецензента, который может помочь облегчить их возможное включение в качестве официально признанного рецензента. Все проблемы в невыполненном обзоре API могут получить предварительное разрешение от лица, не получившего одобрения. Затем эти обзоры пробного запуска могут быть изучены и подвергнуты критике другими рецензентами или утверждающими.

Путь от рецензента к утверждающему требует значительного опыта рецензента, одобрения со стороны наставника и множества успешно завершенных обучающих обзоров. Начинающие утверждающие могут подать прошение о включении в файл OWNERS, отправив электронное письмо в списки рассылки SIG-Architecture и Kubernetes-api-reviewers с темой « Запрос на API Утверждающий Статус » со ссылками на все заполненные обзоры за предыдущий шестимесячный период.Если все текущие утверждающие LGTM проблему, то заявитель может открыть PR для файла OWNERS с добавлением своего имени.

Чтобы получить квалификацию, претенденты на утверждение должны сослаться как минимум на 5 предварительных проверок новых типов API и 10 предварительных проверок изменений существующих типов API без существенных разногласий или дополнений со стороны утверждающего. Начинающие утверждающие должны быть в состоянии продемонстрировать свою компетентность как для проверки нового API, так и для решения проблем совместимости с модификациями существующих API.

Указание того, считалась ли предварительная проверка квалификационной, должно быть частью предоставленной критической / коучинговой обратной связи («ваш предварительный обзор уловил все важное, что я видел, +1»)

Обзоры обучения

Для тех, кто желает стать официальными рецензентами, процесс имеет альтернативный путь, при котором обзоры API, не зависящие от времени, могут быть сначала проверены, а затем совместно изучены с утверждающим лицом / наставником. Это может быть выполнено асинхронно в виде комментариев в проверочном документе или, в идеале, путем объединения в пары на проверке утверждающего.

После того, как предварительная проверка была принята утверждающим лицом, она поступает к отправителям так же, как и в обычном процессе.

По мере того, как начинающие рецензенты приобретают навыки, они могут объединиться с утверждающим в ходе срочных проверок, чтобы лучше понять процесс с меньшим влиянием на продолжительность проверки.

Начинающим рецензентам следует обратиться к модератору в случае слабости. Модератор добавит их в список потенциальных рецензентов и назначит обзоры обучения по мере их появления.

Надежды на будущие итерации этого процесса

• Сделайте видео об этом процессе в качестве руководства для участников

• Ознакомьтесь с документом об условных обозначениях API на предмет актуальности и организованности

• Разделяйте и храните отдельные части, относящиеся к процессу и соглашениям API, во всех наших документах. Таким образом, люди, не участвующие в нашем процессе, смогут прочитать более сжатый набор документов о том, как создавать хорошие API.

• Рассмотрим новый дом для наших документов API, который будет красивее, чем уценка со вкусом Github (новая вкладка в kubernetes.io или новый сайт)

• Учитывая уровень полноты соглашений, этот процесс должен генерировать документацию недокументированных соглашений, которые могут быть уже существующими или новыми.

• В идеале этот процесс должен поддаваться некоторой автоматизации. В настоящее время этого не происходит. [TBD: создайте общий вопрос для этого]

  • Мы уже помечаем PR с помощью api-change

  • Нам следует рассмотреть возможность автоматической генерации документов об изменениях API из openapi или, по крайней мере, упростить просмотр набора изменений

  • Мы должны автоматизировать механические проверки API

• Мы можем захотеть перейти к идее и процессу для «теневых рецензентов», изложенным в ссылке [1]

• Нам нужно обновить другие документы, чтобы они указывали на этот документ

• Обновление документов для изменений функций.мкр

• Api_changes.md

• Api-conventions.md

• Pull-requests.md — необходимо обновить, чтобы особо выделять изменения API как важные

• Owners. md — необходимо обновить

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

• Вероятно, нам следует пересмотреть все изменения API в выпуске в рамках создания документации в качестве «последней возможности» гарантировать, что мы не отправим то, что не хотим поддерживать.

• Нам нужен специальный процесс для «информационных» или необязательных обзоров

• https: // docs.google.com/document/d/1OkSQngGem7xaENqaO8jzHLDSSIGh3obPUaJGAFDwTUE/edit?disco=AAAAB_-Yzjw

Список литературы

[1] https://storage.googleapis.com/pub-tools-public-publication-data/pdf/45294.pdf

[2] http://wiki.netbeans.org/APIReviews

[3] https://cwiki.apache.org/confluence/display/TS/API+Review+Process

[4] https://docs.google.com/document/d/135PQSFTDqUmxsBhG7ZwMYtfWnJ3XTirsdAvytlkzOd0/

[5] https://github.com/kubernetes/community/pull/419

Bazaarvoice | Чтение ответа клиента

API Bazaarvoice Response позволяет программно управлять ответами на отзывы.Чтобы узнать больше, перейдите на домашнюю страницу документации Response API.

На этой странице описано, как:

• Получить ответ с обзором конкретного клиента
• Получить все ответы клиентов на данный обзор

Получить ответ с обзором конкретного клиента

Запрос ограничен определенным ресурсом с помощью GUID этого ресурса.

Запрос



Требуется HTTP GET.

https: // [stg.] api.bazaarvoice.com / response / v1 / clientResponses / {responseGuid}? passkey = {RESPONSE_API_PASSKEY} HTTP / 1.1

Авторизация: предъявитель {ACCESS_TOKEN}
…
 



Старые приложения могут использовать https: // [stg.] Api.bazaarvoice.com/ contentmanagement в качестве базового URL-адреса для Response API вместо https: // [stg.] Api.bazaarvoice.com / ответ . URL-адрес Contentmanagement устарел. Однако Bazaarvoice продолжит поддерживать приложения, использующие URL-адрес Contentmanagement , до дальнейшего уведомления.

Эллипсы (…) в приведенном выше примере указывают на то, что ваше приложение может генерировать другие заголовки.

Параметры

Ответ

Заголовок

Статус HTTP 200 указывает на успех.Другие значения заголовка задокументированы в обзоре.

Кузов

Ответ будет содержать объект JSON в теле. Следующее демонстрирует типичный успешный GET записи ответа клиента:

{
    "данные": [
        {
            "тип": "clientResponse",
            "id": "XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX",
            "attributes": {
                "отдел": "Название отдела",
                "response": "Это образец ответа клиента.",
                "responseBy": "Имя владельца приложения OAuth",
                "responseSource": "Название приложения, созданного для OAuth",
                "created": "2018-06-22T19: 55: 03Z",
                "обновлено": "2018-06-22T19: 55: 03Z"
            },
            "отношения": {
                "author": {
                    "данные": {
                        "тип": "автор",
                        "id": "Dav OAuth"
                    },
                    "links": {
                        "self": "https: // [stg.] api.bazaarvoice.com/response/v1/clientResponses/XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX/relationships/author ",
                        "related": "https: // [stg.] api.bazaarvoice.com/response/v1/clientResponses/XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX/author"
                    }
                },
                "рассмотрение": {
                    "данные": {
                        "тип": "обзор",
                        "id": "75266",
                        "имя клиента": "{}"
                    },
                    "links": {
                        "self": "https: // [stg.] api.bazaarvoice.com/response/v1/clientResponses/XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX/relationships/review ",
                        "related": "https: // [stg.] api.bazaarvoice.com/response/v1/clientResponses/XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXX/review"
                    }
                }
            },
            "links": {
                «self»: ​​«https: // [stg.] api.bazaarvoice.com/response/v1/clientResponses/XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX»
            }
        }
    ],
    "links": {
        "self": "https: // [stg.] api.bazaarvoice.com/response/v1/clientResponses/ {client_name} / reviews / {reviewId}? passkey = {RESPONSE_API_PASSKEY} "
    }
}
 

Определение ключей и значений, возвращаемых в теле ответа, задокументировано в обзоре.

Значения responseBy и responseSource в ответе получаются из приложения OAuth, созданного Bazaarvoice при предоставлении доступа к Response API.

Содержимое узла отношений предоставляется как часть спецификации JSON API.

Ошибки

Подробное описание и решение ошибок Response API см. В разделе «Устранение неполадок».

Получить все отзывы клиентов о данном обзоре

Запрос ограничен определенным ресурсом обзора с помощью reviewId.



Требуется HTTP GET.

ПОЛУЧИТЬ https: // [stg.] Api.bazaarvoice.com/response/v1/clientResponses/ {client} / reviews / {reviewId}? Passkey = {RESPONSE_API_PASSKEY} HTTP / 1.1

Авторизация: предъявитель {ACCESS_TOKEN}
…
 



Старые приложения могут использовать https: // [stg.] api.bazaarvoice.com/ contentmanagement в качестве базового URL для Response API вместо https: // [stg.] api.bazaarvoice.com/ response . URL-адрес Contentmanagement устарел. Однако Bazaarvoice продолжит поддерживать приложения, использующие URL-адрес Contentmanagement , до дальнейшего уведомления.

Эллипсы (…) в приведенном выше примере указывают на то, что ваше приложение может генерировать другие заголовки.

Запрос

Параметры

Ответ

Заголовок

Статус HTTP 200 указывает на успех. Другие значения заголовка задокументированы в обзоре.

Кузов

Ответ будет содержать объект JSON в теле. Следующее демонстрирует типичный успешный GET записи ответа клиента:

{
    "данные": [
        {
            "тип": "clientResponse",
            "id": "XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX",
            "attributes": {
                "отдел": "Название отдела",
                "response": "Это образец ответа клиента.",
                "responseBy": "Имя владельца приложения OAuth",
                "responseSource": "Название приложения, созданного для OAuth",
                "created": "2018-06-22T19: 55: 03Z",
                "обновлено": "2018-06-22T19: 55: 03Z"
            },
            "отношения": {
                "author": {
                    "данные": {
                        "тип": "автор",
                        "id": "Dav OAuth"
                    },
                    "links": {
                        "self": "https: // [stg.] api.bazaarvoice.com/response/v1/clientResponses/XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX/relationships/author ",
                        "related": "https: // [stg.] api.bazaarvoice.com/response/v1/clientResponses/XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX/author"
                    }
                },
                "рассмотрение": {
                    "данные": {
                        "тип": "обзор",
                        "id": "75266",
                        "clientName": "{client}"
                    },
                    "links": {
                        "self": "https: // [stg.] api.bazaarvoice.com/response/v1/clientResponses/XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX/relationships/review ",
                        "related": "https: // [stg.] api.bazaarvoice.com/response/v1/clientResponses/XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXX/review"
                    }
                }
            },
            "links": {
                «self»: ​​«https: // [stg.] api.bazaarvoice.com/response/v1/clientResponses/XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX»
            }
        },
        {
        .....
        },
        {
        .....
        },
        {
        .....
        }
    ]
}
 

Определение ключей и значений, возвращаемых в теле ответа, задокументировано в обзоре.

Ошибки

Подробное описание и решение ошибок Response API см. В разделе «Устранение неполадок».

Неверный ключ доступа API

 
 Разработчик неактивен 
 
 

Жетон плохого предъявителя

{
    «httpCode»: 403,
    "requestURI": "/ response / v1 / clientResponses / {client} / reviews / {reviewId}",
    "ошибки": [
        {
            «код»: «OAUTh3_INVALID_ACCESS_TOKEN»,
            "field": "Авторизация",
            "message": "Недействительный токен доступа"
        }
    ]
}
 

Неверное имя клиента

{
    «httpCode»: 500,
    "requestURI": "/ response / v1 / clientResponses / {client} / reviews / {reviewId}",
    "ошибки": [
        {
            «код»: «ВНУТРЕННЯЯ_СЕРВЕР_ОШИБКА»,
            "поле": "",
            "message": "Не удалось получить отзыв для {client}: {reviewId}"
        }
    ]
}
 

ошибок API индексирования | Разработчики Google

В этом документе указаны некоторые коды ошибок и сообщения, возвращаемые API Google.В частности, перечисленные здесь ошибки относятся к глобальному домену или домену по умолчанию для API Google. Многие API-интерфейсы также определяют свои собственные домены, которые идентифицируют специфичные для API-интерфейсов ошибки, не относящиеся к глобальному домену. Для этих ошибок значение свойства domain в ответе JSON будет специфичным для API значением, например youtube.parameter .

На этой странице перечислены ошибки по их кодам состояния HTTP, как определено в RFC 7231.

Пример ответа JSON ниже демонстрирует, как передается глобальная ошибка:

{
 "ошибка": {
  "ошибки": [
   {
    "домен": " глобальный ",
    "причина": "недопустимый параметр",
    "message": "Недопустимое строковое значение: 'asdf'.Допустимые значения: [mostpopular] ",
    "locationType": "параметр",
    "местоположение": "диаграмма"
   }
  ],
  «код»: 400,
  "message": "Недопустимое строковое значение: 'asdf'. Допустимые значения: [mostpopular]"
 }
}
 

Ошибки

1. ПЕРЕМЕЩЕННО ВСЕГДА (301)
2. SEE_OTHER (303)
3. НЕ МОДИФИЦИРОВАНО (304)
4. TEMPORARY_REDIRECT (307)
5. BAD_REQUEST (400)
6. НЕАВТОРИЗОВАННЫЙ (401)
7. ТРЕБУЕТСЯ ОПЛАТА (402)
8. ЗАПРЕЩЕНО (403)
9. НЕ НАЙДЕНО (404)
10. МЕТОД_NOT_ALLOWED (405)
11. КОНФЛИКТ (409)
12. УШЕНО (410)
13. PRECONDITION_FAILED (412)
14. REQUEST_ENTITY_TOO_LARGE (413)
15. REQUESTED_RANGE_NOT_SATISFIABLE (416)
16. EXPECTATION_FAILED (417)
17. ТРЕБУЕТСЯ ПРЕДВАРИТЕЛЬНАЯ ИНФОРМАЦИЯ (428)
18. TOO_MANY_REQUESTS (429)
19. ВНУТРЕННИЙ_СЕРВЕР_ОШИБКА (500)
20. НЕ ВЫПОЛНЕНО (501)
21. СЛУЖБА_НЕВОЗМОЖНА (503)

ПЕРЕМЕЩЕННО ВСЕГДА (301)

SEE_OTHER (303)

НЕ МОДИФИЦИРОВАНО (304)

TEMPORARY_REDIRECT (307)

BAD_REQUEST (400)

НЕСАНКЦИОНИРОВАННОЕ (401)

ТРЕБУЕТСЯ ОПЛАТА (402)

ЗАПРЕЩЕНО (403)

НЕ НАЙДЕНО (404)

РАЗРЕШЕННЫЙ МЕТОД (405)

КОНФЛИКТ (409)

УШЕНО (410)

PRECONDITION_FAILED (412)

REQUEST_ENTITY_TOO_LARGE (413)

REQUESTED_RANGE_NOT_SATISFIABLE (416)

EXPECTATION_FAILED (417)

ТРЕБУЕТСЯ ПЕРЕДАЧА (428)

TOO_MANY_REQUESTS (429)

ВНУТРЕННИЙ_СЕРВЕР_ОШИБКА (500)

НЕ ВЫПОЛНЕНО (501)

СЛУЖБА_НЕВОЗМОЖНА (503)

Ошибки, связанные с индексированием API

Во всех перечисленных ниже случаях запрос был отклонен, и Google не сканирует URL-адрес. Это также относится к основным сообщениям об ошибках.

BAD_REQUEST (400)

ЗАПРЕЩЕНО (403)

TOO_MANY_REQUESTS (429)

Как использовать Yelp API

Сбор полезных данных о предприятиях и событиях в регионе может быть трудным. Существует множество API-интерфейсов, которые содержат полезные данные, в том числе API Google Адресов.Другой популярный и ценный API, предлагающий аналогичную информацию, предоставляется Yelp.

Yelp API может быть полезен веб-разработчикам, создающим приложения на основе платформы Yelp, а также специалистам по данным, которые хотят использовать большой набор данных о местоположении. В этом посте мы рассмотрим некоторые полезные части Yelp API. Наши примеры будут ориентированы на разработчиков javascript, но все они являются обычными HTTP-запросами, поэтому концепции должны быть перенесены на любой язык.

Для начала давайте сначала рассмотрим два формата API, предлагаемых Yelp.

Два основных формата API

Yelp предлагает две основные точки входа в свои данные. Их REST API, Yelp Fusion и новый GraphQL API. Оба предлагают одинаковый уровень доступа, поэтому вам решать, что вы предпочитаете. Стоит отметить, что версия GraphQL считается «экспериментальной». В нашем использовании мы обнаружили несколько небольших причуд, таких как локализация, но в остальном он полнофункциональный. В этом посте мы покажем примеры вызовов REST API и запросов к конечной точке GraphQL.Если вы хотите использовать GraphQL API, вам необходимо присоединиться к программе Developer Beta. Это можно сделать на странице «Управление приложением», а также по любой из ссылок в документации по GraphQL API.

Документация Fusion предлагает полный список конечных точек, а также параметры, которые можно использовать.

GraphQL API предлагает примеры запросов для всех доступных запросов, а также включает интерактивную консоль (построенную поверх GraphiQL).

Yelp также предлагает множество частных API.К ним относятся API транзакций, рекламы и знаний. Чтобы запросить доступ, вам необходимо напрямую связаться с Yelp (через формы на каждой странице API).

Создайте приложение и найдите свой ключ API

Чтобы начать работу с Yelp API, вам потребуется учетная запись с доступом. Сделайте это, создав учетную запись Yelp на портале разработчика. Вы также можете использовать существующую учетную запись пользователя Yelp.

Выберите раздел «Управление приложением» на портале разработчика.

Заполните обязательные поля, сохраните новое приложение, и вам будет предоставлен ключ API Yelp и идентификатор клиента.Идентификатор клиента больше не требуется. Обязательно сохраните свой ключ API, так как он вам вскоре понадобится.

Вы можете вернуться на эту страницу в любое время, чтобы просмотреть свой ключ, сбросить ключ API, просмотреть использование и внести любые изменения в настройки вашего приложения. Это также страница, на которой вы можете присоединиться к бета-тестированию для разработчиков, чтобы включить экспериментальные функции (например, GraphQL API).

Как подключиться к Yelp API

Для всех наших примеров мы будем использовать Node.js и Axios. Если вы следуете инструкциям, убедитесь, что npm установил axios в свой проект и потребует его вверху.Вам также понадобится ваш ключ API из предыдущего раздела.

Аутентификация выполняется путем отправки заголовка Authorization со значением Bearer YOUR_API_KEY . Остальной API использует URL-адрес https://api.yelp.com/v3 , за которым следует конечная точка, которую вы хотите запросить. Все конечные точки REST доступны только для чтения и принимают запросы GET .

API GraphQL принимает тот же заголовок для аутентификации и использует https://api.yelp.com/v3/graphql в качестве своего URL-адреса.Он принимает запросов POST и ожидает полезную нагрузку запроса {ВАШ ЗАПРОС} .

Для всех наших примеров мы будем использовать следующий код Node.js.

Для REST API вызовы будут выглядеть так:

  const axios = require ("axios")

let API_KEY = "ВАШ_API_KEY"

// ОТДЫХ
пусть yelpREST = axios.create ({
  baseURL: "https://api.yelp.com/v3/",
  заголовки: {
    Авторизация: `Bearer $ {API_KEY}`,
    "Content-type": "application / json",
  },
})

yelpREST (КОНЕЧНАЯ ТОЧКА, {параметры: {ключ: значение}}).затем (({data}) => {
  // Что-то делаем с данными
})
  

Для GraphQL API вызовы будут выглядеть так:

  // GraphQL
пусть yelpGQL = axios.create ({
  url: "https://api.yelp.com/v3/graphql",
  заголовки: {
    Авторизация: `Bearer $ {API_KEY}`,
    "Content-type": "application / json",
  },
  метод: "POST",
})

yelpGQL ({data: JSON.stringify ({query: `{ВАШ ЗАПРОС}`})}). затем (
  ({данные}) => {
    // Что-то делаем с данными
  }
)
  

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

Что вы можете сделать

Теперь, когда вы знаете, как подключиться к Yelp API, давайте посмотрим, что вы можете сделать.

Поиск информации о компании

Лучшее место для начала — поиск предприятий. Вы можете найти полный список конечных точек, связанных с бизнесом, в документации. Наиболее распространенным будет / search .

Для поиска компании вам необходимо ввести поисковый запрос и некоторую информацию о местоположении.Для вызовов REST конечной точкой будет предприятий / поиск . Это требует, чтобы вы предоставили хотя бы данные о местоположении. Это может быть в форме параметров строки запроса широты и долготы или строки location , описывающей местоположение. Например, «Нью-Йорк» или «NW 23rd Ave, PDX». Вы можете уточнить результаты, указав строку термин . В нашем примере мы будем искать кофе в Киото.

С REST API это становится:

  // Использование помощника yelpREST, который мы определили ранее
yelpREST ("/ предприятия / поиск", {
  params: {
    локация: "киото",
    термин: "кофе",
    предел: 10,
  },
}).затем (({data}) => {
  пусть {предприятия} = данные
  business.forEach ((b) => {
    console.log ("Имя:", b.name)
  })
})
  

В GraphQL тот же вызов API использует поиск , запрос :

  // Использование помощника yelpGQL, который мы определили ранее
yelpGQL ({
  данные: JSON.stringify ({
    query: `{
    search (термин: "кофе",
            локация: "киото",
            limit: 10) {
        бизнес {
            название
        }
    }
} `,
  }),
}). then (({data}) => {
  // Двойные данные: данные - это то, что Axios помещает в тело ответа, но это также и то, что возвращает GraphQL
  пусть предприятия = данные.data.search.business
  business.forEach ((b) => {
    console.log ("Имя:", b.name)
  })
})
  

Примечание. В этом примере на момент написания этой статьи вы могли заметить, что GraphQL API не всегда правильно реагирует на параметр locale . REST API по умолчанию - "en_US", поэтому результаты для каждого из них могут отличаться по языку.

В результате мы получили 10 результатов для кофе в районе Киото. Вот некоторые из вещей, которые вы можете сделать с ответом от этой конечной точки:

• Вытяните фотографий , который предоставляет URL-адреса 3 фотографий для каждой компании.
• Измените уровень цены в своем запросе и просмотрите уровень цены в ответе.
• См. Отрывки отзывов с полем отзывов .
• Получите перечисленные часов бизнеса.
• Захватите Yelp ID компании (он понадобится нам в следующем разделе).

Посмотреть отзывы

Еще один отличный вариант, особенно если вы создаете что-либо, связанное с данными о местоположении, - это получать отзывы для предприятий.Yelp предоставляет до 3 отзывов на каждую компанию в порядке «сортировки Yelp». Каждый содержит подробную информацию об обзоре и прямую ссылку на отдельный отзыв.

При использовании REST API идентификатор компании Yelp является частью конечной точки. Например:

  // Наш предыдущий помощник REST
yelpREST ("/ business / 9QFiF_YBCKvWsUu50G_yxg / reviews"). then (({data}) => {
  console.log (данные)
})
  

С GraphQL тот же запрос выглядит так:

  // Наш помощник GQL
yelpGQL ({
  данные: JSON.stringify ({
    query: `{
      отзывы (бизнес: "9QFiF_YBCKvWsUu50G_yxg") {
        общее
        рассмотрение {
          url
          я бы
          рейтинг
          текст
        }
      }
    } `,
  }),
}). then (({data}) => {
  console.log (данные)
})
  

Вы заметите, что Yelp ID используется с аргументом business в запросе reviews .

Некоторые интересные вещи, которые вы можете использовать на ресурсе Reviews :

• Получить всего отзывов и использовать их, чтобы сделать предположения о популярности
• Усредните оценки трех результирующих обзоров, чтобы получить приблизительное представление о рейтинге компании.

Использовать автозаполнение Yelp

С помощью API автозаполнения Yelp вы можете автоматически заполнять строку текста, чтобы соответствовать названиям категорий, предприятиям и предложениям терминов, которые соответствуют типам вещей, которые пользователи ищут в Yelp.

Автозаполнение работает с конечной точкой / autocomplete в REST API. Это единственный ресурс, который доступен только из REST API и не предлагается в GraphQL API.

Вот пример в Fusion API:

  yelpREST ("/ autocomplete", {
  params: {
    расположение: "pdx",
    текст: "спотыкаться",
  },
}).затем (({data}) => {
  console.log (данные)
})
  

В результатах показаны такие термины, как «Кофе в пеньках», но также и «Удаление пней». API автозаполнения может быть полезен в качестве шлюза к более подробным запросам, но, как и со всеми автозаполнениями, будьте осторожны, чтобы не отправлять слишком много запросов за короткий промежуток времени.

То, что нельзя делать

При наличии действительно ценных данных есть вещи, которые нельзя делать с общедоступными API. Самое главное - это изменение данных. Если вашими клиентами являются компании, использующие Yelp, вы не сможете ничего публиковать с помощью Yelps API.Однако могут быть возможности для подобной функциональности на платформе Yelp, хотя в настоящее время она ориентирована на транзакции.

В общем, вы должны добросовестно использовать данные. Это означает, что не нужно его экономить и обслуживать самостоятельно. Обязательно ознакомьтесь с условиями использования API и ознакомьтесь с тем, как эффективно использовать бренд Yelp.

Пределы скорости

Если вы интенсивно используете API, в какой-то момент вы будете вынуждены ограничить количество обращений. И Fusion API, и GraphQL API имеют определенные ограничения скорости, которые можно найти в документации.Если вы получили код состояния HTTP 429, вы достигли предела. Все запросы отправляются с заголовками с префиксом RateLimit, которые сообщают вам дневной лимит и оставшиеся запросы. Вы также можете просмотреть их на экране «Управление приложением».

Хорошая новость заключается в том, что если вы достигнете пределов, Yelp предложит контактную информацию для запроса более высокого уровня. На это стоит обратить внимание, если вы сильно полагаетесь на их данные. Еще один отличный вариант - встроить в свой код резервные функции или постепенные откаты.

Fusion VIP

Для разработчиков, которым нужен более интегрированный подход с более высокими лимитами, большим объемом данных и меньшими ограничениями на получаемые вами ответы (больше изображений!), Вы можете запросить участие в программе Fusion VIP. В них не указаны конкретные требования, но, по сути, это уровень API «одобренного приложения».

Завершение

Yelp предлагает большой объем данных бесплатно через свой API. Это отличный способ включить локальные результаты в ваше приложение и повысить ценность существующей функциональности.Потратьте некоторое время на изучение их документации по API, чтобы узнать, чего еще вы можете достичь.

Вы создаете что-нибудь интересное с помощью Yelp API или хотите его интегрировать? Дайте нам знать @BearerSH. Мы создаем инструмент, чтобы все ваши интеграции API работали лучше и работали более надежно. Если API выходит из строя, наш агент может автоматически исправить неудавшиеся запросы. Возникли проблемы с отладкой вызова? Наша система ведения журнала может помочь. Посмотрите, что мы создаем в Bearer сегодня.

  {
"заказы": [
{...}, // эти объекты сами по себе вложены.
{...}
]
}  

  ToString (ToDate (CASE WHEN
(COALESCE ($ _ PACKAGE_LAST_SUCCESSFUL_JOB_SUBMISSION_TIMESTAMP, '') == '' ИЛИ
$ full_load == 1) ТОГДА '1900-01-01T00: 00: 00Z' ИНАЧЕ
$ _PACKAGE_LAST_SUCCESSFUL_JOB_SUBMISSION_TIMESTAMP
КОНЕЦ), 'гггг-ММ-дд \\' Т \\ 'ЧЧ: мм: сс').