HTTP-аутентификация

gsqlcmd поддерживает следующие методы HTTP-аутентификации:

• Auto
• None
• Basic
• Windows
• Forms
• OAuth2
• OAuth1
• Custom

Используйте опцию /auth, чтобы указать метод.

Например, используйте метод None для запроса с пустым заголовком авторизации:

gsqlcmd download https://localhost/crm/contacts /auth=None

Метод по умолчанию - Авто.

Используйте опцию /interactive, чтобы разрешить авторизацию запроса в интерактивном режиме.

Например:

gsqlcmd download https://localhost/crm/contacts /interactive

Вы можете использовать опции /options, /clientJson, /serviceJson и /tokenJson для загрузки параметров аутентификации из JSON или текстовых файлов.

Например, команда с аутентификацией OAuth2 может выглядеть так

gsqlcmd download https://localhost/crm/contacts /clientJson=client.json /serviceJson=service.txt /tokenJson=token.json

Все параметры можно разместить в одном файле. Например:

gsqlcmd download https://localhost/crm/contacts /options=options.txt

Однако первый подход позволяет разделить параметры клиента и службы и обновлять файл token.json при обновлении токена.

Ниже вы найдете советы по конкретным методам аутентификации.

Базовая аутентификация

Для метода аутентификации Basic требуется имя пользователя и пароль.

Например:

gsqlcmd download https://localhost/crm/contacts /auth=basic /username=user /password=pass

Вы можете опустить опцию /auth=basic, так как gsqlcmd автоматически определяет эту схему аутентификации.

Аутентификация Windows

Вы можете использовать метод проверки подлинности Windows с учетными данными пользователя Windows по умолчанию или с указанным именем пользователя и паролем.

Например:

gsqlcmd download https://localhost/crm/contacts /auth=windows

gsqlcmd download https://localhost/crm/contacts /auth=windows /username=user /password=pass

В имени пользователя можно указать домен. Например:

gsqlcmd download https://localhost/crm/contacts /auth=windows /username=domain/user /password=pass

Вы можете опустить опцию /auth=windows, так как gsqlcmd автоматически определяет схему аутентификации Windows.

Аутентификация с помощью форм

Вы можете использовать имя пользователя и пароль, если служба поддерживает проверку подлинности Forms.

Например:

gsqlcmd download https://localhost/crm/contacts /auth=forms /username=user /password=pass

В противном случае вы можете использовать интерактивный режим, как показано выше, или указать куки авторизации.

Например:

gsqlcmd download https://localhost/crm/contacts /auth=forms /cookie=.ASPXFORMSAUTH=D3A...

Вы можете найти такие файлы cookie в инструментах разработчика браузера.

Лучшим вариантом является размещение файла cookie в файле и использование опции /cookieFile.

В этом случае gsqlcmd самостоятельно обновляет cookie в заданном файле.

Например:

gsqlcmd download https://localhost/crm/contacts /auth=forms /cookieFile=cookie.txt

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

Вы можете опустить параметр /auth=forms, так как gsqlcmd в большинстве случаев успешно определяет схему аутентификации с помощью форм.

Когда указаны имя пользователя и пароль, gsqlcmd определяет URL авторизации. В некоторых случаях утилита не может определить его правильно.

В этом случае укажите корневой URL службы в опции /authorizationUrl.

Например:

gsqlcmd download https://localhost/crm/contacts /auth=forms /username=user /password=pass /authorizationUrl=https://localhost/crm/

Аутентификация OAuth2

Если у вас есть токен доступа, вы можете использовать простую форму, подобную этой

gsqlcmd download https://localhost/crm/contacts /auth=oauth2 /tokenType=Bearer /accessToken=token

Эта форма эквивалентна запросу:

gsqlcmd download https://localhost/crm/contacts "/header=Authorization: Bearer token"

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

gsqlcmd имеет достаточный набор опций для настройки любых конкретных требований.

Мы рекомендуем разделить параметры на три файла и использовать их в любой команде с аутентификацией OAuth2. Например:

gsqlcmd ... /clientJson=client.json /serviceJson=service.json /tokenJson=token.json ...

Вы можете использовать следующие режимы gsqlcmd с аутентификацией OAuth2:

• download, convert, import
• get-token
• refresh-token
• revoke-token

Сначала используйте режим get-token, чтобы получить токен доступа. В качестве альтернативы используйте опцию /interactive в режимах download, convert или import.

Используйте режим refresh-token для явного обновления токена. Обычно это действие не требуется, так как gsqlcmd автоматически обновляет токены при необходимости.

Используйте режим revoke-token, чтобы отозвать токен.

Пример конфигурации Zoho CRM

Ниже приведен полный пример файлов конфигурации для Zoho CRM.

Рекомендуемое содержимое файла service.txt:

authorization_url_format={authorization_url}?scope={scope}&client_id={client_id}&response_type=code&access_type=offline&redirect_uri={redirect_uri}
authorization_url=https://accounts.zoho.com/oauth/v2/auth

get_token_url_format={accounts-server}/oauth/v2/token
get_token_body_format=grant_type=authorization_code&client_id={client_id}&client_secret={client_secret}&redirect_uri={redirect_uri}&code={code}

refresh_token_url_format={accounts-server}/oauth/v2/token?refresh_token={refresh_token}&client_id={client_id}&client_secret={client_secret}&grant_type=refresh_token
refresh_token_body_format=

revoke_token_url_format={accounts-server}/oauth/v2/token/revoke?token={refresh_token}
revoke_token_body_format=

Файл содержит параметры gsqlcmd, такие как /authorization_url_format, /authorization_url и так далее.

Файл содержит определение форматов URL и тела запроса для каждой операции get-token, refresh-token и revoke-token, а также получения первоначальной авторизации.

Форматы содержат переменные в фигурных скобках, которые получают значения из других опций gsqlcmd, указанных в командной строке или загружаемых из файлов.

Вы можете найти эти значения в документации по сервису, например, https://www.zoho.com/crm/developer/docs/api/v2/oauth-overview.html для Zoho CRM.

Рекомендуемое содержимое файла client.txt:

client_id=1000...
client_secret=93a...
redirect_uri=https://www...
scope=ZohoCRM.modules.ALL

Форматы файла service.txt используют значения из этого файла.

Значения клиента получаются при регистрации приложения.

Например, посмотрите https://www.zoho.com/crm/developer/docs/api/v2/register-client.html для Zoho CRM.

Выберите тип мобильного приложения при регистрации приложения в Zoho CRM.

Когда вы настроили параметры клиента и службы, получите токен с помощью команды, подобной этой

gsqlcmd get-token /clientJson=client.txt /serviceJson=service.txt /tokenJson=token.json

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

Утилита сохранит токен в файле token.json, который для Zoho CRM выглядит следующим образом:

{
    "location":"us",
    "accounts-server":"https://accounts.zoho.com",
    "valid_to":"2021-03-10T00:36:15.850Z",
    "access_token":"1000.ee9764918066eb3a9ee2b58c00ed4737.28c820e4ef4400000000000000000741",
    "refresh_token":"1000.cedae4432cd94039e2a402bf29bc293b.17906477b8c900000000000000000071",
    "api_domain":"https://www.zohoapis.com",
    "token_type":"Bearer",
    "expires_in":"3600"
}

Вы можете видеть значения, подходящие для опций gsqlcmd, таких как /tokenType и /accessToken, которые обсуждались выше.

Кроме того, можно видеть специфичные для службы значения, такие как location, accounts-server и api_domain (которые также используются в service.txt).

gsqlcmd автоматически обнаруживает такие значения и сохраняет их в файле токенов.

Список полей можно определить явно, используя опцию /tokenFields.

Когда вы получили токен, вы можете загрузить данные с помощью такой команды:

gsqlcmd download https://www.zohoapis.com/crm/v2/Contacts contacts.json /clientJson=client.txt /serviceJson=service.txt /tokenJson=token.json

Или вы можете загрузить и преобразовать данные с помощью такой команды:

gsqlcmd convert "SELECT Email, First_Name AS FirstName, LastName AS LastName FROM https://www.zohoapis.com/crm/v2/Contacts" contacts.csv ^
    /clientJson=client.txt /serviceJson=service.txt /tokenJson=token.json

Пример конфигурации Google Search Console

Ниже приведен более простой пример файлов конфигурации для Google Search Console.

Создайте идентификатор клиента OAuth типа настольного приложения на странице https://console.cloud.google.com/apis/credentials/oauthclient.

Сохраните учетные данные клиента в формате JSON, используя ссылку "DOWNLOAD JSON", и переименуйте его в client.json.

Содержимое файла выглядит так:

{"installed":{
    "client_id":"586418743564-9p0vq6cq8nmjmhgucsm0000000000000.apps.googleusercontent.com",
    "project_id":"searchconsoleapi-000000",
    "auth_uri":"https://accounts.google.com/o/oauth2/auth",
    "token_uri":"https://oauth2.googleapis.com/token",
    "auth_provider_x509_cert_url":"https://www.googleapis.com/oauth2/v1/certs",
    "client_secret":"Aii500000000000000000FCB",
    "redirect_uris":["urn:ietf:wg:oauth:2.0:oob","https://localhost"]
}}

Файл содержит полную конфигурацию службы, включая учетные данные клиентского приложения.

gsqlcmd использует token_uri в качестве значения по умолчанию для опций /getTokenUrl и /requestTokenUrl.

Кроме того, gsqlcmd использует стандартные форматы URL и тела запроса OAuth2, которых достаточно для Google.

На втором шаге получить токен можно с помощью команды:

gsqlcmd get-token /clientJson=client.json /tokenJson=token.json

Затем используйте любой режим для загрузки, преобразования или импорта данных из Google Search Console с помощью команды со следующими опциями:

gsqlcmd ... /clientJson=client.json /tokenJson=token.json

См. подробности на странице https://developers.google.com/webmaster-tools/v1/searchanalytics/query.

Аутентификация OAuth1

Чтобы авторизовать запрос по двух-шаговой схеме OAuth1, укажите опции /consumerKey и /consumerSecret.

Например:

gsqlcmd download https://localhost/crm/contacts /consumerKey=app /consumerSecret=appSecret

Опция /auth=OAuth1 является необязательным.

Чтобы авторизовать запросы с помощью трех-шаговой схемы OAuth1, вначале следует получить токен доступа.

Вы можете создать файл client.txt со следующим содержимым и заполнить значения в соответствии с сервисной документацией и вашим зарегистрированным приложением.

consumer_key=
consumer_secret=
callback=
request_token_url=
authorization_url=
access_token_url=

Затем получите токен доступа с помощью команды:

gsqlcmd get-token /clientJson=client.txt /tokenJson=token.json

Затем используйте любой запрос для загрузки, преобразования или импорта данных из службы, используя команду, подобную этой:

gsqlcmd ... /clientJson=client.json /tokenJson=token.json

Специфические методы аутентификации

Вы можете использовать настраиваемый метод аутентификации для аутентификации запросов с использованием параметров URL, заголовков авторизации и файлов cookie.

Например:

gsqlcmd download https://localhost/crm/contacts /urlParameters=api_key=key "/authorizationHeader=Bearer token" /cookieFile=cookie.txt

Этот метод может быть проще для нескольких сервисов.

Например, https://data.nasdaq.com/ бесплатно публикует множество данных. Для запросов требуется ключ API в URL-адресе.