Protocolo de fio
Nesta página
- Visão geral
- Clientes compatíveis
- Cadeias de conexão
- Credenciais
- Região
- Parâmetros
- Habilitar conexões de protocolo de fio
- Conecte-se através do protocolo de fio
- Conecte-se ao Atlas App Services com uma connection string
- Ler e modificar dados
- Chamar uma função
- Chame uma ação de serviço [OUSOS]
- Obtenha os dados do usuário conectado
Visão geral
O Atlas App Services implementa nativamente um subconjunto do protocolo de conexão MongoDB , que permite que você se conecte a um aplicativo por meio de uma de suas fontes de dados vinculadas do MongoDB Atlas usando drivers e ferramentas padrão do MongoDB . Os clientes usam uma connection string especializadado App Services para conectar e enviar solicitações. O App Services oferece suporte à maioria dos recursos do cliente através do protocolo de conexão, incluindo regras de acesso a dados baseadas em função, funções e ações de serviço .
Esta é uma boa opção para idiomas que não têm atualmente um Realm SDK. Os exemplos aqui são para Python, C++11 e o mongo shell. Qualquer driver do MongoDB que ofereça suporte ao parâmetro de string de conexão appName
pode usar o protocolo de conexão para se conectar ao App Services.
Observação
As fontes de dados federadas não suportam conexões por meio do protocolo de conexão.
Clientes compatíveis
Você pode usar as seguintes ferramentas e drivers para se comunicar com o App Services usando uma string de conexão:
Versão 4.0+ do shell mongo.
Qualquer driver MongoDB que ofereça suporte ao parâmetro de string de conexão
appName
. Todos os drivers oficiais do MongoDB suportam este parâmetro em suas versões atuais.
Observação
As conexões com o App Services através do protocolo de conexão têm acesso à funcionalidade completa do Serviço MongoDB. No entanto, o App Services não oferece suporte a todas as operações e recursos disponíveis em ferramentas e clientes padrão. Para obter detalhes, consulte Limitações do Serviço MongoDB .
Cadeias de conexão
Para se conectar ao App Services pelo protocolo de conexão , você deve construir uma string de conexão do MongoDB que inclua credenciais de um usuário do aplicação e um parâmetro de query appName
específico do aplicativo.
Importante
Codificação de URL
Você deve URL codificar connection strings antes de usá-las para se conectar ao Atlas App Services. As connection strings na interface do usuário do Atlas App Services são codificadas corretamente por padrão.
As connection strings do App Services têm o seguinte formato:
mongodb://<credentials>@<region>.services.cloud.mongodb.com:27020/?<parameters>
Credenciais
Todas as operações que você emite pelo protocolo de fio são executadas no contexto de um usuário de aplicativo específico que você especifica na connection string. O usuário deve ser registrado com um dos seguintes fornecedores de autenticação:
O conteúdo das credenciais da connection string depende do provedor de autenticação com o qual o usuário se registrou:
Formatar | <email>:<password> | ||||
Campos |
| ||||
Exemplo |
|
Formatar | _:<apiKey> | ||
Campos |
| ||
Exemplo |
|
Formatar | _:<customAuthToken> | |||
Campos |
| |||
Exemplo |
|
Região
A string de conexão deve especificar a região de implantação e o provedor de nuvem no qual o aplicativo está hospedado.
Aplicativos globais usam a região global
:
mongodb://<credentials>@global.services.cloud.mongodb.com:27020/?<parameters>
Os aplicativos locais especificam o provedor de nuvem e o nome da região usando o formato <region>.<cloud>
. Por exemplo, um aplicativo implementado no aws-us-east-1
usaria a seguinte string de conexão:
mongodb://<credentials>@us-east-1.aws.services.cloud.mongodb.com:27020/?<parameters>
Parâmetros
O App Services requer opções de string de conexão específicas que identificam o aplicativo ao qual você deseja se conectar e o provedor de autenticação associado às credenciais fornecidas.
As connection strings do App Services têm os seguintes parâmetros de query:
Parâmetro | Descrição | |||||||
---|---|---|---|---|---|---|---|---|
authMechanism | Este parâmetro deve ser sempre configurado para PLAIN . | |||||||
authSource | Este parâmetro deve ser sempre configurado para $external . | |||||||
appName | Identifica exclusivamente o aplicativo, serviço MongoDB e fornecedor de autenticação ao qual você deseja se conectar. O parâmetro
|
Habilitar conexões de protocolo de fio
Você deve habilitar conexões de protocolo de conexão para clusters vinculados para poder se conectar a um App Services App com uma string de conexão.
Obtenha a versão mais recente da sua aplicação
Para habilitar conexões de protocolo de conexão MongoDB com o App Services CLI, você precisa de uma cópia local dos arquivos de configuração do seu aplicativo.
Para extrair uma cópia local da versão mais recente do seu aplicativo, execute o seguinte:
appservices pull --remote="<Your App ID>"
Dica
Você também pode baixar uma cópia dos arquivos de configuração do seu aplicativo na tela Deploy > Export App na interface do usuário do App Services.
Habilitar protocolo de fio para o cluster
Para habilitar conexões de protocolo de conexão para um cluster vinculado, abra o arquivo config.json
do cluster e defina o valor de config.wireProtocolEnabled
para true
:
{ "name": "mongodb-atlas", "type": "mongodb-atlas", "config": { "wireProtocolEnabled": true, ... } }
Observação
As fontes de dados federadas não suportam conexões por meio do protocolo de conexão.
Implemente a Configuração da Fonte de Dados Atualizada
Depois de habilitar as conexões de protocolo de conexão para o cluster em config.json
, você poderá enviar a configuração para seu aplicativo remoto. O App Services CLI implementa imediatamente a atualização no push.
appservices push --remote="<Your App ID>"
Conecte-se através do protocolo de fio
Conecte-se ao Atlas App Services com uma connection string
Para se conectar ao Atlas App Services através do protocolo de fio, passe um codificado por URL Atlas App Services string ao criar um cliente, da mesma forma que faria com uma connection string comum.
mongo "mongodb://<user>:<password>@services.cloud.mongodb.com:27020/?authMechanism=PLAIN&authSource=%24external&ssl=true&appName=realm-application-abcde:mongodb-atlas:local-userpass"
mongocxx::instance instance{}; mongocxx::uri uri("mongodb://<user>:<password>@services.cloud.mongodb.com:27020/?authMechanism=PLAIN&authSource=%24external&ssl=true&appName=realm-application-abcde:mongodb-atlas:local-userpass"); mongocxx::client client(uri);
client = pymongo.MongoClient("mongodb://<user>:<password>@services.cloud.mongodb.com:27020/?authMechanism=PLAIN&authSource=%24external&ssl=true&appName=realm-application-abcde:mongodb-atlas:local-userpass")
Ler e modificar dados
Enquanto estiver conectado ao através Atlas App Services do protocolo de fio, você pode usar MongoDB CRUD operações padrão do . Atlas App Services aplica regras de acesso a dados baseadas em função a todas as queries no contexto do usuário autenticado especificado nas string credenciais da connection .
> use HR > db.employees.findOne(); { "_id": ObjectId("5ae782e48f25b9dc5c51c4a5"), "employeeId": 854271626, "name": { "first": "Lucas", "last": "Lewis" }, "role": "PM", "salary": 200000, "email": "Lucas.Lewis.0271@company.com", "password": "<password>", "manager": { "id": 328892725, "email": "Daniel.Wilson.0474@company.com", "name": { "first": "Daniel", "last": "Wilson" } } }
mongocxx::database db = client["HR"]; mongocxx::collection employees = db["employees"]; bsoncxx::stdx::optional<bsoncxx::document::value> result = collection.find_one({}); if(result) { std::cout << bsoncxx::to_json(result) << "\n"; }
"HR"] db = client["employees"].find_one(); employee = db[ pprint(employee){'_id': ObjectId('5ae782e48f25b9dc5c51c4a5'), 'email': 'Lucas.Lewis.0271@company.com', 'employeeId': 854271626.0, 'manager': {'email': 'Daniel.Wilson.0474@company.com', 'id': 328892725.0, 'name': {'first': 'Daniel', 'last': 'Wilson'}}, 'name': {'first': 'Lucas', 'last': 'Lewis'}, 'password': '<password>', 'role': 'PM', 'salary': 200000}
Chamar uma função
Você pode chamar funções usando o comando callFunction
banco de dados.
Comando | Descrição | Prototype | ||||
---|---|---|---|---|---|---|
Chama a função especificada e retorna qualquer resultado. |
|
db.runCommand({ ... callFunction: "getEmployeeById", ... arguments: ["5ae782e48f25b9dc5c51c4a5"] ...}); { "ok" : 1, "response" : { "_id": ObjectId("5ae782e48f25b9dc5c51c4a5"), "employeeId": 854271626, "name": { "first": "Lucas", "last": "Lewis" }, "role": "PM", "salary": 200000, "email": "Lucas.Lewis.0271@company.com", "password": "<password>", "manager": { "id": 328892725, "email": "Daniel.Wilson.0474@company.com", "name": { "first": "Daniel", "last": "Wilson" } } } }
db.runCommand({ callFunction: "getEmployeeById", arguments: ["5ae782e48f25b9dc5c51c4a5"] });
"callFunction", "getEmployeeById", function_result = db.command("5ae782e48f25b9dc5c51c4a5"] arguments=[...) pprint.pprint(function_result){'ok': 1, 'response': {'_id': ObjectId('5ae782e48f25b9dc5c51c4a5'), 'email': 'Lucas.Lewis.0271@company.com', 'employeeId': 854271626.0, 'manager': {'email': 'Daniel.Wilson.0474@company.com', 'id': 328892725.0, 'name': {'first': 'Daniel', 'last': 'Wilson'}}, 'name': {'first': 'Lucas', 'last': 'Lewis'}, 'password': '<password>', 'role': 'PM', 'salary': 200000}}
Chame uma ação de serviço [OUSOS]
Você pode chamar ações de serviço usando o comando de banco de dados callServiceFunction
.
Comando | Descrição | Prototype | |||||
---|---|---|---|---|---|---|---|
Chama a ação de serviço especificada e retorna qualquer resultado. |
|
> db.runCommand({ ... callServiceFunction: "get", ... service: "http", ... arguments: [{ url: "https://jsonplaceholder.typicode.com/todos/1" }] ... }); { "ok" : 1, "response" : { "status" : "200 OK", "statusCode" : 200, "contentLength" : NumberLong(-1), "headers" : { "Content-Type" : ["application/json; charset=utf-8"], "Connection" : ["keep-alive"], "Vary" : ["Origin, Accept-Encoding"], "X-Content-Type-Options" : ["nosniff"], "Via" : ["1.1 vegur"], "X-Powered-By" : ["Express"], "Cf-Cache-Status" : ["HIT"], "Expect-Ct" : ["max-age=604800, report-uri=\"https://example.com/cdn-cgi/beacon/expect-ct\""], "Set-Cookie" : ["__cfduid=d7f650e765d41beb7598ce2ab62d0c0191536867096; expires=Fri, 13-Sep-19 19:31:36 GMT; path=/; domain=.typicode.com; HttpOnly"], "Access-Control-Allow-Credentials" : ["true"], "Cache-Control" : ["public, max-age=14400"], "Pragma" : ["no-cache"], "Etag" : ["W/\"53-hfEnumeNh6YirfjyjaujcOPPT+s\""], "Server" : ["example.com"], "Cf-Ray" : ["459d08f88e1e56db-IAD"], "Date" : ["Thu, 13 Sep 2018 19:31:36 GMT"], "Expires" : ["Thu, 13 Sep 2018 23:31:36 GMT"] }, "cookies" : { "__cfduid" : { "value" : "d7f650e765d41beb7598ce2ab62d0c0191536867096", "path" : "/", "domain" : ".typicode.com", "expires" : "Mon, 01 Jan 0001 00:00:00 GMT", "maxAge" : 0, "secure" : false, "httpOnly" : true } }, "body" : BinData(0,"ewogICJ1c2VySWQiOiAxLAogICJpZCI6IDEsCiAgInRpdGxlIjogImRlbGVjdHVzIGF1dCBhdXRlbSIsCiAgImNvbXBsZXRlZCI6IGZhbHNlCn0=") } }
db.runCommand({ callServiceFunction: "get", service: "http", arguments: [{ url: "https://jsonplaceholder.typicode.com/todos/1" }] });
"callServiceFunction", "get", result = db.command("http", service="url": "https://jsonplaceholder.typicode.com/todos/1"}] arguments=[{...) pprint.pprint(result){'ok': 1, 'response': {'body': b'{\n "userId": 1,\n "id": 1,\n "title": "delectus aut' b' autem",\n "completed": false\n}', 'contentLength': -1, 'cookies': {'__cfduid': {'domain': '.typicode.com', 'expires': 'Mon, 01 Jan 0001 00:00:00 ' 'GMT', 'httpOnly': True, 'maxAge': 0, 'path': '/', 'secure': False, 'value': 'd4b10004e96ca7fee0be03dceebaf2ab71536866400'}}, 'headers': {'Access-Control-Allow-Credentials': ['true'], 'Cache-Control': ['public, max-age=14400'], 'Cf-Cache-Status': ['HIT'], 'Cf-Ray': ['459cf7fc7e20c1bd-IAD'], 'Connection': ['keep-alive'], 'Content-Type': ['application/json; charset=utf-8'], 'Date': ['Thu, 13 Sep 2018 19:20:00 GMT'], 'Etag': ['W/"53-hfEnumeNh6YirfjyjaujcOPPT+s"'], 'Expect-Ct': ['max-age=604800, ' 'report-uri="https://example.com/cdn-cgi/beacon/expect-ct"'], 'Expires': ['Thu, 13 Sep 2018 23:20:00 GMT'], 'Pragma': ['no-cache'], 'Server': ['example.com'], 'Set-Cookie': ['__cfduid=d4b10004e96ca7fee0be03dceebaf2ab71536866400; ' 'expires=Fri, 13-Sep-19 19:20:00 GMT; ' 'path=/; domain=.typicode.com; ' 'HttpOnly'], 'Vary': ['Origin, Accept-Encoding'], 'Via': ['1.1 vegur'], 'X-Content-Type-Options': ['nosniff'], 'X-Powered-By': ['Express']}, 'status': '200 OK', 'statusCode': 200}}
Obtenha os dados do usuário conectado
Você pode obter o objeto de usuário para o usuário autenticado usando o comando de banco de dados userProfile
banco de dados.
Comando | Descrição | Prototype | |||
---|---|---|---|---|---|
Retorna o objeto de usuário para o usuário autenticado. |
|
> db.runCommand({ userProfile: 1 }); { "ok" : 1, "profile" : { "userid" : "5ad7a79e8f25b975898d77b8", "domainid" : ObjectId("5ad7a69746224c054067c8b1"), "identities" : [ { } ], "data" : "{\"email\":\"joe.mango@company.com\"}", "type" : "normal", "roleassignments" : [ ] } }
db.runCommand({ userProfile: 1 });
"userProfile", 1) result = db.command( pprint.pprint(result){'ok': 1, 'profile': {'data': '{"email":"joe.mango@company.com"}', 'domainid': ObjectId('5ad7a69746224c054067c8b1'), 'identities': [{}], 'roleassignments': [], 'type': 'normal', 'userid': '5ad7a79e8f25b975898d77b8'}}