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 encode connection strings antes de usá-las para se conectar ao App Services. As connection strings na UI do 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 |
| ||||
Campos |
| ||||
Exemplo | |
Formatar |
| ||
Campos |
| ||
Exemplo | |
Formatar |
| |||
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 | |||||||
|---|---|---|---|---|---|---|---|---|
| Este parâmetro deve ser sempre configurado para | |||||||
| Este parâmetro deve ser sempre configurado para | |||||||
| 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 conectar-se ao App Services através do protocolo de conexão , passe uma string de conexão codificada para URL ao criar um cliente, assim como faria com uma string de conexão normal.
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"; }
db = client["HR"] employee = db["employees"].find_one(); 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"] });
function_result = db.command("callFunction", "getEmployeeById", arguments=["5ae782e48f25b9dc5c51c4a5"] ...) 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}}
Chamar uma ação de serviço
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" }] });
result = db.command("callServiceFunction", "get", service="http", arguments=[{"url": "https://jsonplaceholder.typicode.com/todos/1"}] ...) 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 });
result = db.command("userProfile", 1) pprint.pprint(result) {'ok': 1, 'profile': {'data': '{"email":"joe.mango@company.com"}', 'domainid': ObjectId('5ad7a69746224c054067c8b1'), 'identities': [{}], 'roleassignments': [], 'type': 'normal', 'userid': '5ad7a79e8f25b975898d77b8'}}
